Self-Documenting Code Chapter 32
Self-Documenting Code
Chapter 32
Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s intent Information that can not possibly be
expressed by the code itself
Repeat of Code Tells what the code does in words
Basically useless
Explanation of Code If code is so complicated or confusing
it needs explanation then it probably needs rewriting
Marker in Code Typical example:
// TODO: make changes here
Summary of Code Simple summary of code into one or two
sentences valuable
Description of Code’s Intent A comment at the level of intent explains the
purpose of a section of code. Intent comments operate more at the level of
the problem than at the level of the solution. For example,
get current employee information is an intent comment, whereas
update employeeRecord object is a summary comment in terms of the solution.
Most useful
Information that can not… Copyright notices Confidentiality Etc Not what we’re talking about here
Balance Certainly need a useful amount of
commenting Need to avoid too many comments
If it takes too much time to wade through comments then there’s too much
If there’s as much or more comments than code then there’s too much
Rule of thumb: 1 line of comment for 10 lines of code
Avoid/*---------------------------------------------*//* here’s a difficult style of *//* comment block to maintain *//*---------------------------------------------*/
/********************************* * class * * hard to maintain ***********************************/
Prefer//---------------------------------------------------------// this style is easier because you don’t// have to align the right hand column// you can just copy and paste the dashes// to start and end the block//---------------------------------------------------------
/*********************************************** keep in mind that your code might not be
viewed with a color-coding system************************************************/
“It Takes Too Much Time” It takes more time later and is harder to
debug Commenting after the fact is more difficult
Commenting Techniques Endline comments
Tend to be cryptic Hard to maintain OK for data declarations OK to denote bug fixes OK for marking ends of blocks
Commenting individual lines Complicated line of code Bug repair
Commenting Techniques Commenting paragraphs of code Example from “recover.c”
// get next cluster fat_index=0; if (cluster >= (FAT_ENTRIES/2)) { cluster = cluster-(FAT_ENTRIES/2); fat_index++; } cluster = *(F_tbl[fat_index]+cluster);
Paragraphs Write comments at the level of the code’s
intent Focus on the code itself so that comments
enhance good code Focus paragraph comments on why rather
than how
Code’s intent Better comments
// find '$' in inputString it indicates that the goal
of the loop is to find a $. it still doesn't give you
much insight into why the loop would need to find a $ into the deeper intent of
the loop. Even better
// find the command-word terminator ($)
Coment the Why, not the How
Justify “good style” violations Explain yourself when violating good style to
prevent someone from rewriting code in a better style that could break your code.
Don’t comment tricky code, rewrite it Except if you’re maintaining code and don’t
have the latitude to change it.
Other Comments Flags to bit level
// 0x80 – NW neighbor // 0x40 – N neighbor // 0x20 – NE neighbor
Allowable numeric ranges // this index should never exceed 10000 because…
Global data I prefer a naming convention to solve this:
Example: gMeaningfullyNamedVariable Coded meanings (could use other methods to accomplish this)
Enumerated types // 0 – generic land texture // 1 – herbaceous rangeland texture
Units of numeric data (again, could use other methods) Meters Fahrenheit degrees Etc
Rules of Thumb Keep comments close to the code they describe Document parameters where they’re declared Use Javadoc Differentiate between input and output
Again, I prefer naming
Routines Say what the routine WON’T do, mention legal
input values Document global effects Document source of algorithms Avoid enormous comment blocks
I like some comments before every routine for visual delineation at the very least