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 |