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.GeneralTipsOnComments
r1.1 - 19 Jun 2008 - 11:47 - Main.guest
topic end
Start of topic |
Skip to actions
*General Tips on Comments* --- * Comments should tell the input, output, preconditions, invariants, motivation. Don't worry about how, but concentrate on defining what the code operates on correctly, and the why. (E.g., my version of the long comment below would be mostly definition; Shawn's was procedural.) -- Main.JackSnoeyink - 19 Jun 2008 * Design routines in pseudocode, convert the pseudo code to comments, fill in the actual code to make each line of pseudo-code work correctly, the pseudo-code approach helps you to design the routine correctly before you even start programming. And then the comments become summary or intent comments reminding you of the original solution. * A conflict between code and it's associated comment indicates a bug (probably in both), refactor the code and it's associated comment to be correct * in C++ (and Java), use '//' for single line comments (and endline comments), use '/*...*/' for multi-line comments (and embedded comments) <verbatim> Single-Line Example: // Compute 1-ring of this vertex End-Line example: bResult = BuildOneRing( currVertex, newVertex ); // Compute 1-ring for this vertex Multi-Line Example: /*------------------------------------------------------------------------- Name: BuildOneRing() Desc: Builds the 1-ring for the current vertex Note: (JSS) The 1-ring of a vertex is the list of (the triangles? the incident edges? the neighboring vertices?) in CCW order around the vertex so that any two adjacent items have a triangle between them. If the order is circular, we have a closed loop and an interior vertex. If not, then the current vertex and first and last vertices of the list are all boundary vertices. The vertex must be manifold for the order to be established, otherwise the vertex is called complex (or malformed). (SDB) We compute the one ring by computing predecessor and successor vertices for each non-indicent edge in the incident triangle list, then starting at a vertex and walking CCW using the predecessor list to find the leftmost edge. If the leftmost edge is the same as our starting edge, we have a closed loop, a valid 1-ring, and are on an interior vertex of the mesh. Otherwise, we start from the leftmost edge, and walk CW using the successor list to find the rightmost edge. If the chain from leftmost to rightmost includes all neighboring vertices, we have an open chain, a valid 1-ring, and are on an exterior vertex of the mesh. Otherwise, we have a complex (or malformed vertex). ----------------------------------------------*/ Embedded Example: /*virtual*/ void SPreader::compute_bounds() { } </verbatim> * Make comments as you code, instead of waiting to the end of the project to comment, you almost always run out of time to do the right thing * Performance goals are not a good reason to not comment, if necessary, you can always write a post-process tool to strip out comments before building * Too many comments are as bad as too few. Find an efficient middle ground * As an aside, an IBM study found that 1 comment line per 10 lines of code was most optimal for clarity. Fewer comments than this resulted in hard to understand code, More comments than this also resulted in increased programmer confusion in understanding the code. * Use a commenting style that is easy to maintain, IE avoid unnecessary ornamentation in comment sections <verbatim> // Harder to maintain /*-------------------------------------------------------------------------------- - FILE: spreader.h - - - - CONTENTS: Streaming Pointer Reader Interface - - ... - --------------------------------------------------------------------------------*/ // Slightly easier but still requires exta work //-------------------------------------------------------------------------------- // FILE: spreader.h // // CONTENTS: Streaming Pointer Reader Interface // ... //-------------------------------------------------------------------------------- // Easiest to maintain /*-------------------------------------------------------------------------------- FILE: spreader.h CONTENTS: Streaming Pointer Reader Interface ... --------------------------------------------------------------------------------*/ </verbatim> -- 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
>
GeneralTipsOnComments
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