Your skill will accomplish what the force of many cannot |
|
PerlMonks |
Re^3: Easily catalog subroutines with a synopsis commentby rir (Vicar) |
on Apr 25, 2008 at 21:05 UTC ( [id://682918]=note: print w/replies, xml ) | Need Help?? |
What purpose does a list of one line routine summaries
serve?
... same end in a quicker/easier fashion. 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,
In Section
Meditations
|
|