Skip to topic
|
Skip to bottom
Jump:
TModeling
TModeling Web
TModeling Web Home
Changes
Notify
Index
Search
Webs
BioGeometry
Main
TModeling
TWiki
Edit
Attach
Printable
TModeling.CommentingParagraphsOfCode
r1.1 - 19 Jun 2008 - 11:49 - Main.guest
topic end
Start of topic |
Skip to actions
*Commenting Paragraphs of Code* --- * Write comments at the level of the code's intent * Focus your documentation efforts on the code itself * Focus your paragraph comments on the _why_ rather than the _how_ <verbatim> // If account flag is zero if (accountFlag == 0) ... vs. // Establish a new Account if (accountFlag == 0) ... </verbatim> * Use comments to prepare the reader for what is to follow, scanning only the comments should be enough for the reader of what the code does and where to look for a specific activity of interest. * Make every comment count, don't write comments for the sake of writing comments, too many comments obscure the code, put extra effort into making code more readable rather than into comments * Document surprises and gotcha's, if you used a tricky technique, document it. If you ran into a surprising solution that was nevertheless correct, document it. * Document performance work-arounds, show what the normal straight forward code should be then explain briefly why the tricky approach gives a performance win and thus is justified. <verbatim> // use right shift to divide by two, cuts parent loop time by 75% elementList[ element ] = elementList[ element ] >> 1; </verbatim> * Avoid abbreviations * Differentiate between major and minor comments * Comment anything that gets around an error or an undocumented feature in a language or programming environment * Justify any violations of good programming style * Don't comment tricky code, rewrite it -- Main.ShawnDB - 16 Jun 2008
to top
End of topic
Skip to action links
|
Back to top
Edit
|
Attach image or document
|
Printable version
|
Raw text
|
More topic actions
Revisions: | r1.1
|
Total page history
|
Backlinks
You are here:
TModeling
>
CommentingParagraphsOfCode
to top
Copyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki?
Send feedback