in reply to Perl script commenting assistant

A long time ago, i too used a similar commenting style. Then i started programming in Perl and discovered POD. Sorry, but your code was deprecated long before you posted it ... i recommend you get into POD, it does a much better job of documenting your code. These days i only use single line comments (via #) as minor notes to myself as to why i chose a particular style/solution. Everything else (what the client needs to know) is implemented in POD. Period. That way i can use existing tools to assist. 
use POD or die $!;

[download]
;)

jeffa

L-LL-L--L-LL-L--L-LL-L--
-R--R-RR-R--R-RR-R--R-RR
B--B--B--B--B--B--B--B--
H---H---H---H---H---H---
(the triplet paradiddle with high-hat)

Replies are listed 'Best First'.
Re: (jeffa) Re: Perl script commenting assistant
by Wafel (Novice) on Jul 08, 2003 at 15:20 UTC

    hehe I do use POD, but not for very small meaningless stuff and POD is ugly when it's scattered throughout your code, If you cluster all the POD, you have to skip back and forward, so I include # blocks with the most vital info, and the POD has the real documentation.

    I suggest you substitute die for warn :-p

[reply]
      No sweat. Me? i don't scatter pod. I 'cluster' it in one spot - i like mine at the very end. When i need to modify the POD, i use a split-screen mode in my text editor. That way i can see the method i am documenting easily. Remember, you are not suppose to be reading the POD while you are reading the code (i.e., in your text editor), you are suppose be reading POD via a POD viewer (perldoc). Second, small meaningless stuff is not even worthy of comments in the first place, IMHO. I will use a single # comment to put an author's name in if i grab code from the Monastery, but other than that, i don't bother. It is a waste of time. It's hard enough to keep the POD current with the code, why add another layer? (see Re (tilly) 2 (disagree): Another commenting question, for more on that.)

      And while your suggestion of substituting in warn has been duly noted, that final blurb was an 'inside joke', a reference to the infamous use CGI or die; write up. I'll leave it intact, thank you. ;) 

      use POD or die $!;

      [download]

      UPDATE:
      I almost forgot about using POD as multi-line comments. Personally, i think that # comments are the uglier of the two: 

      # function: foo
# input   : bar baz
# output  : qux
# precond : bar and baz are defined
# postcond: qux is defined
sub foo {
}

      [download]
      versus 
      =for comment
 function: foo
 input   : bar baz
 output  : qux
 precond : bar and baz are defined
 postcond: qux is defined
=cut
sub foo {
}

      [download]
      Two extra lines, but you don't have to worry about prepending #'s. You don't have to have 'valid' POD to create a multi-line comment, by the way. Just a simple =for token to start and =cut to end.

      UPDATE2
      sigh ... you missed my points completely ... did you even read tilly's post?

      jeffa

      L-LL-L--L-LL-L--L-LL-L--
-R--R-RR-R--R-RR-R--R-RR
B--B--B--B--B--B--B--B--
H---H---H---H---H---H---
(the triplet paradiddle with high-hat)
[reply]
[d/l]
[select]
        Ok... blow by blow ;-)

        " you are not suppose to be reading the POD while you are reading the code"

        But I am suppost to document while coding

        It's hard enough to keep the POD current with the code

        I know.. that's why you shouldn't over-use it :-)

        I'll leave it intact, thank you. ;)

        Be brave! Drop tradition! hehe..

        BTW: Are you sure the second one looks better? Must be a matter of taste? ;-)

[reply]

        Nah, i don't think I've missed your point, but I do think commenting style is a matter of taste, and as long as it's serves it's purpose, documentation, it's not a major issue.

        That's also why my reply was intended to be more about humor than anything else.

[reply]

In Section Code Catacombs