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 excuse I hear over and over from programmers who don't write POD, don't write tests, and write incomprehensible code that they can include comments and everything will be OK.

Comments should be the item of last resort. For figuring out what code does, writing clear, concise code is first, followed by Pod, then unit tests and as a last resort, comments.

The reason for doing this in this order,

1. Comments have no relation to how code runs. You can never be sure it is accurate and because they are never publicly (re)viewed, they can easily be ignored when doing updates.
2. Unit tests do two things, test the validity of your code, and give a working example of how it is used. While it does not declare a context the code is supposed to be used, you should be able to write a proof of concept using tests.
3. Pod is documentation that programmers will depend on to use your code. If your Pod is invalid, people will let you know or they stop using your code. It is harder to ignore Pod if you expect people to use code.
4. Code should be first because it is the one thing that is ALWAYS done. Code is not simply a way of executing a particular action, it is instructions to tell the programmer HOW it is supposed to do it.

   If your code is so abstract that people cannot understand it, you have created a Rube Goldberg Machine that cannot be updated easily and will eventually end up being disgarded by something that can.

The one thing I believe in is documentation, just not half-hearted attempts by calling them 'comments.'

The text isn't useless. I describe the use

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

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.

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

sub flip_pancake
[download]

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