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.CheckList
r1.1 - 16 Jun 2008 - 04:13 - Main.guest
topic end
Start of topic |
Skip to actions
*Self Documenting Code Check List:* --- *Classes:* * Does the class interface present a consistent abstraction? * Is the class well named? Does the name describe the central purpose of the class? * Does the class's interface make it obvious how you should use the class? * Is the class's interface abstract enough that you don't have to think about how it's underlying methods are implemented? Can you treat the class as a black box conceptually and in practice? *Routines:* (Functions/Procedures/Methods) * Does each routine's name describe exactly what the routine does? * Does each routine perform one well-defined task? * Have all parts of each routine that would benefit from being put into their own routines been put into their own routines? * Is each routine's interface obvious and clear? *Data Names:* * Are type names descriptive enough to help document data declarations? * Are variables named well? * Are variables only used for the purpose for which they were originally named? * Are loop counters given more informative names than i,j, and k? * Are well-named enumerated types used instead of makeshift flags or boolean variables? * Are named constants used instead of magic number literals or magic string literals? * Do naming conventions distinguish among type names, enumerated types, named constants, local variables, class variables, and global variables? *Data Organization:* * Are extra variables used for clarity when needed? * Are references to variables close together? * Are data types simple so that they minimize complexity? * Is complicated data accessed through abstract access routines (Abstract data types) instead of directly? *Control:* * Is the primary path throught the code clear? * Are related statements grouped together? * Have relatively independent groups of statements been packaged into their own routines? * Does the normal case (most frequently executed) follow the +if_ rather than the _else_? * Are control structures simple so that they minimize complexity? * Does each loop perform one and only one function, as a well-defined routine should do if it replaced the loop? * Is nesting minimized? * Have boolean expressions been simplified by using additional boolean variables, boolean functions, and decision tables? *Layout:* * Does the program's layout show its underlying logical structure? *Design:* * Is the code straightforward? Is it easy to understand? Does it avoid clever programming tricks which mask the underlying algorithm? * Does the code rely on language specific side-effects? * Are implementation details hidden behind a well-defined class interface or routine call? * Is the program written in terms of the actual problem domain as much as possible rather than in terms of computer-science or programming language structures? --- *Good Commenting Technique:* --- *General:* * Can someone pick up the code and immediately start to understand it from just the comments? * Do comments explain the code's intent or summarize what the code does rather than just repeating the code? * Is the Psuedocode Programming Process used to reduce commenting time? * Has tricky code been rewritten rather than commented? * Are comments up to date? * Are comments clear and correct? * Does the comenting style allow comments to be easily modified? * Before the code ships, have all marker comments been removed and properly dealt with? *Individual Line Statements and Paragraphs:* * Does the code avoid endline comments? * Do comments focus on _why_ rather than _how_? * Do comments prepare the reader for the code to follow? * Does every comment count? Have redundant, extraneous, and self-indulgent comments been removed or improved? * Are surprises documented? * Have abbreviations in comments been avoided? * Is code that works around an error or undocumented features commented? *Data Declarations:* * Are units on data declarations commented? * Are the ranges of values on numeric data commented? * Are coded meanings commented? * Are limitations on input data commented? * Are flags documented to the bit level? * Has each global variable been commented where it is declared? * Has each global variable been identified as such at each usage, by a naming convention, a comment, or both? * Are magic numbers replaced with named constants, enumerations, or varaibles rather than just documented? *Control Structures:* * Are comments inserted at their natural spots (control structures or at the beginning of long blocks of code)? * Are the ends of long or complex control structures commented and/or when possible simplified to avoid the need for comments? *Routines:* * Is the purpose of each routine commented? * Are other important facts about the routine given in comments, when relevant, including input and output data, interface assumptions, limitations, error corrections, global side-effects, and sources of algorithms? *Files, Classes, and Programs:* * Does the program have a short usage document? * Does the program have a short design document? * Is the purpose of each file described in a block header at the beginning of each file? * Are the author's contact info included in the block header for each file? * Does each class have a consistent commenting layout used throughout the interface? * Do implementation details of the class remain hidden (IE not spelled out in the interface comments)? -- 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
>
CheckList
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