原创 2004年10月28日 23:14:00

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.

Commenting routines.
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.

Class documentation.
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.

File documentation.
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.


idea fetching documentation解决

使用idea的某天突然发现鼠标放在方法名上时无法获取到javadoc,悬浮框里一致显示fetching documentation… 最后发现了原因是javadoc的获取来源指定了oracle的地址,...
  • t1993ing
  • t1993ing
  • 2016年12月23日 11:43
  • 973


从eclipse换成IDEA各种不习惯,还有很多需要熟悉的地方,随用随记 1、eclipse在调用接口的时候会显示接口的注释文档,但是初用IDEA却没有显示,其实是可以设置的editor->gene...
  • thekenofDIS
  • thekenofDIS
  • 2017年02月22日 14:37
  • 751


下载Android官方SDK文档的方法: 1.昨天我按照方法二下好了一份,大家可以直接下载: (提取码:6075) (如果链接失效,请提...
  • u013647453
  • u013647453
  • 2015年01月21日 11:29
  • 1117

Android Studio一直 Fetching Documentation终极解决方法,绝对有效

大家可能都遇到过 Fetching Documentation问题,这其实是一个科学上网问题。 百度后,网上给出的解决方案(比如
  • tydqcjj
  • tydqcjj
  • 2017年11月28日 14:51
  • 302

AndroidStudio设置不自动弹出 Documentation 窗口

今天用AS在xml码字的时候,每隔2、3秒钟就自动弹出 Documentation窗口,缩小了又自动出来。如下图。好烦!!后来设置了不主动弹出,世界瞬间清净了O_O方法: 打开设置面板。 ...
  • cswhale
  • cswhale
  • 2016年07月18日 14:28
  • 5123

Python 3 文档(简体中文) 3.2.2 documentation
  • jjwspj
  • jjwspj
  • 2012年09月04日 12:45
  • 1496

android解决quick documentation(Ctrl+Q)慢的问题

看图 很久才出来。解决办法第一步:去C:\Users\Administrator.AndroidStudio2.3\config\options下找到jdk.table.xml并打开。 第二步: ...
  • y444400
  • y444400
  • 2017年05月18日 21:55
  • 146

Python 2.7: no documentation found when typing help('print')

原文转自 I...
  • sherry_0009
  • sherry_0009
  • 2013年09月29日 19:26
  • 880


1.菜单栏Xcode->Preferences选择Documentation,在线下载2.离线下载(用迅雷即可下载)在上述在线下载列表中,点击某一列,下拉框可看见 info,可得到其网络所在地址例如:...
  • andypan1314
  • andypan1314
  • 2011年05月13日 14:40
  • 13649

DeepLearning 0.1 documentation中文翻译_内容扉页

本文为《DeepLearning 0.1 documentation》的中文翻译,本人水平有限,如有错误或不当,欢迎批评指正!非常感谢!原文网址:
  • u011335616
  • u011335616
  • 2015年04月02日 12:54
  • 2418