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.CommentArguments
r1.1 - 19 Jun 2008 - 11:39 - Main.guest
topic end
Start of topic |
Skip to actions
*To Comment or Not to Comment:* *Don't Comment Arguments:* (write self-documenting code) * Poorly written or incorrect comments are worse than no comments at all. * Clearly written, well structured, readable code is much more valuable than comments. * Comments degrade over time, the code gets maintained but the associated comments don't. * Good refactoring practices should eliminate comments by replacing comments by well-named single task routines which are self-explainatory. * Comments doubles the amount of code that programmers have to read to achieve understanding *Do Comment Arguments:* (write good useful comments) * Good comments don't repeat the code or explain it, they clarify it's intent, Comments should explain, at a higher level of abstraction than the code, what you are trying to accomplish. * Comments act like a table of contents or chapter headings in a book and allow you to quickly zero in on the code you are interested in * People who don't write comments haven't had the experience of trying to decipher and understand their own code 6 months later... *Actual Solution:* Both approaches should be used, write good self-documenting code and at the same time write good useful comments to summarize code, clarify intent, and provide a higher level of abstraction. -- 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
>
CommentArguments
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