发表于2004/10/28 23:14:00 732人阅读
Kind of comments:
1. Repeat of the code. A repetitious comment restates that the code does in defferent words. It merely give the reader of the code more to read without providing additional information.
2. Explanation of the code. Typically used to explain complicated, tricky, or sensitive pieces of code. But if the code is so complicated that it needs to be explained, it's nearly always better to improve the code than it is to add comments.
3. Marker in the code. It isn't intended to be left in the code. It's a note to the developer that the work isn't done yet.
4. Summary of the code. It distills a few lines of code into one or two sentences.
5. Description of the code's intent. It explains the purpose of a section of code.
Commenting paragraphs of code
Most comments in a well-documented program are one-or two-sentence comments that describe paragraphs of code.
1. Write comments at the level of the code's intent.
2. Focus your documentation efforts on the code itself.
3. Focus paragraph comments on the why rather than the how.
4. Use comments to prepare the reader for what is to follow.
5. Make every comment count.
6. Document surprise.
7. Avoid abbreviations.
8. Differentiate between major and minor comments.
9. Comments anything that gets around an error or an undocumented feature in a language or an environment.
10. Justify vialations of good programming style.
11. Don't comment tricky code.
Commenting data declarations.
1. Comment the unit of numeric data.
2. Comment the range of allowable numeric values.
3. Comment coded meanings.
4. Comment limitations on input data
5. Document flags to the bit level.
6. Stamp comments related to a variable with the variable's name.
7. Document global data.
Commenting control structures.
1. Put a comment before each block of statement, if, case, or loop
2. Comment the end of each control structure.
3. Treat end-of-loop comments as a warning indicating complicated code.
1. Keep comments close to the code they describe.
2. Describe each routine in one or two sentences at the top of the routine.
3. Document parameters where they are declared.
4. Differentiate between input and output data.
5. Document interface assumptions.
6. Document on the routine's limitations
7. Document the routine's global effects.
8. Document the source of algorithms that are used.
9. Use comments to mark parts of your program.
1. Describe the design approach to the class.
2. Describe limitations, usage assumptions, and so on.
3. Comment the class interface.
4. Don't document implementation details in the class interface.
1. Describe the purpose and content of each file.
2. Put your name, email addressm, and phone number in the block comment.
3. Include a copyright statement in the block comments.
4. Give the file a name related to its contents.
Android Studio一直 Fetching Documentation终极解决方法，绝对有效
tydqcjj 2017-11-28 14:51 113
受限玻尔兹曼机_DeepLearning 0.1 documentation中文翻译
u011335616 2017-03-13 14:11 1372
apache编译安装，解决configure: error: APR not found . Please read the documentation问题！
superbirds 2016-08-30 21:34 1817
hjw199089 2017-05-05 19:37 157
深度学习教程_DeepLearning 0.1 documentation中文翻译
u011335616 2015-03-25 20:55 3178
Luohsh1 2013-01-31 22:57 376
Android.mk File [documentation.html]
gg137608987 2012-05-15 16:43 1337
TDS Protocol Documentation
dsjlzh 2012-02-02 16:00 589