Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot
 
PerlMonks  

Re^3: Easily catalog subroutines with a synopsis comment

by rir (Vicar)
on Apr 25, 2008 at 21:05 UTC ( [id://682918]=note: print w/replies, xml ) Need Help??


in reply to Re^2: Easily catalog subroutines with a synopsis comment
in thread Easily catalog subroutines with a synopsis comment

What purpose does a list of one line routine summaries serve?

... same end in a quicker/easier fashion.

sub flip_pancake
Also more robust. As you say, this only goes so far, but your technique doesn't go much further.

The problem with your technique is that it doesn't scale well. Once a routine requires more text than you want on a line, you are tempted to abbreviate your comment unreasonably. Once you have more developers involved the technique is destroyed by formatters and pretty printers.

Comments and documentation are time and/or space travelers. When I write comments as you've described; and I have over years. I write them now and bury them in a time capsule; when I dig them up three years hence, I find I am a different person. A person who finds them useless for being redundant or for being obscure. It is for that future person that I should write.

The comments I am apt to put on that line are too close to the code. Not too close textually or lexically, but too close in meaning--they say the same thing almost the same way. They shed the same light as the code; by being so similar, they can be understood or misconstrued in the same manner as the code.

The more experience I have with comments that have aged, the less value I usually find in the brief ones.

Having a better tool than a simple grep helps; consider the B or C options to grep or things like ctags.

Be well,
rir

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others having a coffee break in the Monastery: (5)
As of 2024-04-19 22:50 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found