Please offer an example of how to go about achieving the same end in a quicker/easier fashion. Currently I'm unable to see the points you raise as relevent and valid.

• The text isn't useless. I describe the use.
• Changing code often leads to changing comments, regardless of where they are. This synopsis is only likely to need updating as often as you change the meaning of the function name. With a stable API, that shouldn't happen.
• More detailed documentation, where warranted, is in no way precluded by adding a synopsis.
• I would find 5 lines of POD in each function I document with a synopsis more work, harder to ignore when editing, and much less suited to my original purpose.

I would find that code that reads like it is supposed to be doing would be better than comments or 5 lines of POD. If the code is complex than encapsulating it in a subroutine that describes what it does would be appropriate as well.

I am tired of crappy code that uses one or two letter variables, or subroutines that last for 500+ lines and the excuse for them not writing clearly because they can use "Comments" to describe what it is doing later. If they cannot write clear code, why do they believe that their comments are going to be any better?

And I am tired of excuses to not document...

--hsm

"Never try to teach a pig to sing...it wastes your time and it annoys the pig."

The text isn't useless. I describe the use

To me, the proposed "synopsis" is useless (given sub name, source, possibly with comment and/or pod, ctags).

More detailed documentation, where warranted, is in no way precluded by adding a synopsis.

Synopsis of a sub would already be listed at the beginning of the (sub) documentation.

As for the original purpose of searching files with synopsis, assuming POD which has sub name on =item line ...

# GNU egrep.
egrep -A 5 '^=item.+<sub name>' <file list>
[download]

... adjust N (= 5 above) to your liking. Whole thing can be easily wrapped so that one would need to supply only sub name regex & file names.

I agree, if you document all your subroutines as you describe, the synopsis line is redundant.

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

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

sub flip_pancake
[download]

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