Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl: the Markov chain saw
 
PerlMonks  

RFC: Filter::Comment::C

by kosmo (Novice)
on Jul 26, 2007 at 15:11 UTC ( [id://628950]=perlmeditation: print w/replies, xml ) Need Help??

Greetings, Monks!

I am still rather new to Perl Monks and have just this morning uploaded my first CPAN module, Filter::Comments::C, which is supposed to provide a mechanism to use C-style block comments, in order to make commenting large blocks of code easier.

Off the bat, do you see any issues? Actually, do you even see a use for such a module. I know there is some worthless code in there, such as the $self->{Start} parameter (which is a line marker of where a comment started if I'm in a comment). I thought I'd need it when I started, but turned out to be nothing useful. What could be done to improve it, and what other tests would you implement? I am already looking at implementing a few others (Kwalitee, as well as some POD checks). I was going to put in C++ style comments (//), but then my colleague, Trizor, reminded me that 5.10 will use '//' as an operator. Do you think I should still implement it as an optional feature or have the source filter only like that commenting style if it matches m/^\/\// or something?

Keep in mind... This is my first released module. So please be harsh about any mistakes, so they won't come up again.

Replies are listed 'Best First'.
Re: RFC: Filter::Comment::C
by mr_mischief (Monsignor) on Jul 26, 2007 at 16:21 UTC
    I apologize if I'm too blunt. I think there's a point that needs to be made clearly here.

    Let me ask a few questions, please. Have you tried POD? Have you found it lacking in some way? If POD is an issue, does your text editor not allow you to automatically insert hash signs at the beginning of a line?

    Please don't take this the wrong way, but I'm honestly not sure if the quality of your code is all that important. Perl has both its own comment syntax and an expanded comments standard that can automatically be turned into documentation (POD).

    While it's true that TIMTOWTDI, bringing in C, Pascal, C++, Basic, and COBOL methods of making comments and adding runtime complexity to projects in order to avoid becoming comfortable with Perl's own strengths and customs seems like overkill.

    While I do think there could be a use for your module, I think that use would be simply to guide C programmers who are new to Perl into their own programming backwater that discourages them from using POD. They and the Perl community would be poorer for that happening.

    Basically, not only are you trying to solve a solved problem, but your module could actually have a negative impact both on the projects using it and the programmers who find it before they take the minimal time involved in learning basic POD skills.

    I applaud your desire to help out and the work you put into making this a CPAN module. I just think this particular module was a little misguided.
Re: RFC: Filter::Comment::C
by eyepopslikeamosquito (Archbishop) on Jul 27, 2007 at 02:41 UTC

    Why the use 5.008008? If you want your module to be widely used, you'll need to support more than just the latest Perl version. As to how ancient a Perl version you support, that is something of a black art, depending on the type of module, its typical users, ... and how much pain you can stand. ;-)

    For some general advice on writing CPAN modules, see:

    Before you uploaded your first CPAN module, you should have chosen a module name and sketched out its interface, then posted it here or on the module-authors@perl.org mailing list, requesting feedback. Had you done that, someone would have doubtless mentioned Acme::Comment, and you may have chosen not to write your module at all.

    Also, it is vital to focus on interface early and to strive to get it right first time, because once your module is released into the wild, any change you make to its interface will break your existing users' code (anything else can be easily fixed in later releases). For some general advice on how to design an interface, see On Interfaces and APIs.

Re: RFC: Filter::Comment::C
by TStanley (Canon) on Jul 26, 2007 at 18:10 UTC
    You might also want to check out the Acme::Comments module as well.

    TStanley
    --------
    People sleep peaceably in their beds at night only because rough men stand ready to do violence on their behalf. -- George Orwell
      Thanks! I had been searching high and low for such a module, but couldn't find any. I guess looking through ACME should have been on my mind. Oh well.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlmeditation [id://628950]
Approved by Corion
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others chilling in the Monastery: (3)
As of 2024-03-29 05:52 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found