Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in...
-
Upload
william-poole -
Category
Documents
-
view
230 -
download
0
Transcript of Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in...
![Page 1: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/1.jpg)
Self-Documenting Code
Chapter 32
![Page 2: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/2.jpg)
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
![Page 3: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/3.jpg)
Repeat of Code Tells what the code does in words
Basically useless
![Page 4: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/4.jpg)
Explanation of Code If code is so complicated or confusing
it needs explanation then it probably needs rewriting
![Page 5: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/5.jpg)
Marker in Code Typical example:
// TODO: make changes here
![Page 6: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/6.jpg)
Summary of Code Simple summary of code into one or two
sentences valuable
![Page 7: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/7.jpg)
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
![Page 8: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/8.jpg)
Information that can not… Copyright notices Confidentiality Etc Not what we’re talking about here
![Page 9: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/9.jpg)
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
![Page 10: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/10.jpg)
Avoid/*---------------------------------------------*//* here’s a difficult style of *//* comment block to maintain *//*---------------------------------------------*/
/********************************* * class * * hard to maintain ***********************************/
![Page 11: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/11.jpg)
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************************************************/
![Page 12: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/12.jpg)
“It Takes Too Much Time” It takes more time later and is harder to
debug Commenting after the fact is more difficult
![Page 13: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/13.jpg)
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
![Page 14: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/14.jpg)
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);
![Page 15: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/15.jpg)
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
![Page 16: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/16.jpg)
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 ($)
![Page 17: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/17.jpg)
Coment the Why, not the How
![Page 18: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/18.jpg)
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.
![Page 19: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/19.jpg)
Don’t comment tricky code, rewrite it Except if you’re maintaining code and don’t
have the latitude to change it.
![Page 20: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/20.jpg)
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
![Page 21: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/21.jpg)
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
![Page 22: Self-Documenting Code Chapter 32. Kinds of Comments Repeat of code Explanation of code Marker in code Summary of code Description of code’s.](https://reader035.fdocuments.in/reader035/viewer/2022081508/56649f2b5503460f94c46518/html5/thumbnails/22.jpg)
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