I believe I understood what was said, but I may not have
understood it like you wanted me to.
My point is this. Saying "minimal" indicates that one
should not view verbose commenting as a way to turn
bad code into maintainable code. Saying "sufficient" bears
no such implication. Cutting loose with volumious comments
is sufficient but not minimal.
Hopefully we find ourselves in agreement on what kind
of code is best for maintainability. However one we are in
agreement on that, then the question is what kind of
statements will lead people to that end. My contention
is that it is better if you say minimal. First that
statement already makes it clear that there are are
things which cannot reasonably said with clear variable
naming. Second it makes it clearer that comments do not
substitute for what can be said through good naming. And
finally it makes the point that while further things
need to be said, it is is a maintainability issue to
say them at too much length.
Saying sufficient communicates more strongly that there
are things that cannot be said through good naming which
need to be said through comments. But it does not stress
that commenting can be overdone, and does not indicate to
what extent comments don't replace naming.
Now which message is more important to get across clearly
depends on what your audience is. However it is my belief
that the message indicated by "minimal" is more likely to
be applicable to the random PerlMonk than the message
indicated by "sufficient". Perhaps a better phrase is
With minimal comments that are sufficient to the
Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
Read Where should I post X? if you're not absolutely sure you're posting in the right place.
Please read these before you post! —
Posts may use any of the Perl Monks Approved HTML tags:
You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
- a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
Link using PerlMonks shortcuts! What shortcuts can I use for linking?
See Writeup Formatting Tips and other pages linked from there for more info.
| & || & |
| < || < |
| > || > |
| [ || [ |
| ] || ] ||