in reply to Easily catalog subroutines with a synopsis comment

I tend to add comments above the sub, usually only 1 line, and beginning the comments with ## to make them easier to search for. 

## comment line
sub dothis {

[download]

Now for a brief rant. Too many programmers do not adequately document their code unless someone is standing over them wielding a club. Many find documentation an unpleasant task, however one of the strengths of Perl, TIMTOWTDI, can become a weakness for those who rely too much on "read the source". I give blogical ++ for sharing a simple technique that works for him, and may also work for others.

Fearest thou not to document, lest thy code shall be shunned by others

Replies are listed 'Best First'.
Re^2: Easily catalog subroutines with a synopsis comment
by mr_mischief (Monsignor) on Apr 18, 2008 at 15:26 UTC
    I tend to use this style as well.

    I also tend to do my searching inside my editor, so it being on the same line isn't as important for me. If I need to find quickly which file the sub is declared in, I'll do a grep for the sub foo { line, but then I'll open that file in an editor and search for the line. I then have plenty of context on the screen to see above the declaration and below.

    Helping get options for ways to document that may help other monks is a good thing, and the discussion has even more ways noted. I'd like to thank everyone who has something constructive to say on how they document their code.

[reply]
[d/l]

In Section Meditations