First let me add my thanks for a good tutorial on technical
writing.
However I do have one small disagreement. The article that
you link to by Drew Sikora offers what I consider to be
horrible advice on commenting. He obviously gives short
shrift to the real issues with how commenting style ages
as code is maintained. He also fails to appreciate the
importance and value of making code definitive. When
you first write them your bug count in code and comments
is approximately the same. But you catch errors in
your code. You never see the ones in your comments. So
if code and comment disagree (as they will from time to
time) the code is rather more likely to be correct. And
given that, what is the point of detailed comments that
undermine the code? (In fact in some of his demonstration
code he has exactly that issue. The comment suggests that
+= should be =. Yet he thinks that you should gloss over
it? Huh?)
This is not to say that I don't think you should comment.
You should. But you shouldn't comment in the ways that
he recommends, or about the things that he says you should
comment about. I could go on about this at length, but
I won't bother doing so now because I already
did. :-)
UPDATE
s/thrift/shrift/ (thanks to grinder for catching it)
Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
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:
- 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
Outside of code tags, you may need to use entities for some characters:
| |
For: |
|
Use: |
| & | | & |
| < | | < |
| > | | > |
| [ | | [ |
| ] | | ] |
Link using PerlMonks shortcuts! What shortcuts can I use for linking?
See Writeup Formatting Tips and other pages linked from there for more info.
|
|