Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??
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)


In reply to Re (tilly) 1: Introduction to Technical Writing/Documentation by tilly
in thread Introduction to Technical Writing/Documentation by ailie

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others sharing their wisdom with the Monastery: (8)
As of 2024-04-25 11:48 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found