EEPW论坛

   程序员在写代码的时候，注意为代码加注释，并以合理的格式为代码加注释，这样就方便别人查看代码，也方便自己以后查看了。

1. 逐层注释 为每个代码块添加注释，并在每一层使用统一的注释方法和风格。例如：

• 针对每个类：包括摘要信息、作者信息、以及最近修改日期等；
• 针对每个方法：包括用途、功能、参数和返回值等。

在团队工作中，采用标准化的注释尤为重要。当然，使用注释规范和工具(例如C#里的XML，Java里的Javadoc)可以更好的推动注释工作完成得更好。

 

2. 使用分段注释

如果有多个代码块，而每个代码块完成一个单一任务，则在每个代码块前添加一个注释来向读者说明这段代码的功能。例子如下：

01	// Check that all data records

3行后添加注释

如果多行代码的每行都要添加注释，则在每行代码后添加该行的注释，这将很容易理解。例如：

1	const MAX_ITEMS = 10; // maximum number of packets

2	const MASK = 0x1F; // mask bit TCP

在分隔代码和注释时，有的开发者使用tab键，而另一些则使用空格键。然而由于tab键在各编辑器和IDE工具之间的表现不一致，因此最好的方法还是使用空格键。

 

4. 不要侮辱读者的智慧 避免以下显而易见的注释：写这些无用的注释会浪费你的时间，并将转移读者对该代码细节的理解。

1	if (a == 5) // if a equals 5

2	counter = 0; // set the counter to zero

5. 关注要点

不要写过多的需要转意且不易理解的注释。避免ASCII艺术，搞笑，诗情画意，hyperverbosity的注释。简而言之，保持注释简单直接。

 6. 使用一致的注释风格

一些人坚信注释应该写到能被非编程者理解的程度。而其他的人则认为注释只要能被开发人员理解就行了。

7. 使用特有的标签

在一个团队工作中工作时，为了便于与其它程序员沟通，应该采用一致的标签集进行注释。例如，在很多团队中用TODO标签表示该代码段还需要额外的工作。

1	int Estimate(int x, int y)

2

{

3	// TODO: implement the calculations

4

return 0;

5

}

 8. 在写代码时添加注释

 

在写代码时就添加注释，这时在你脑海里的是清晰完整的思路。如果在代码最后再添加同样注释，它将多花费你一倍的时间。

9. 为自己注释代码

当注释代码时，要考虑到不仅将来维护你代码的开发人员要看，而且你自己也可能要看。用Phil Haack大师的话来说就是：“一旦一行代码显示屏幕上，你也就成了这段代码的维护者”。因此，对于我们写得好(差)的注释而言，我们将是第一个受益者(受害者)。----（非完全原创来自http://iteye.blog.163.com/blog/static/186308096201271923859587/）

原来为代码注释这么重要，学习了。

写两个自己常用的，供借鉴：

//todo 溢出处理

//有时写的思如泉涌，左右逢源，不忍心停下来去写边边角角的代码，比如溢出等错误处理，打算之后再写，那么就加上todo 和要todo的东西，等下次打开工程搜索todo就知道哪里要写什么了，其实就是自行添加任务，这个功能在VS的IDE里是直接集成的。

//debug

//类似的，有时有些代码是为了debug才放进去的，不会影响程序的最终效果但是可能影响程序效率，个别时候懒得写debug条件编译，就用个debug标签告诉自己这几个代码是debug时候用的，最后程序成型的时候搜索debug ，好把代码注释掉或删除掉。

2楼很详细啊

简单的说：主要是方便程序的调试、使用与修改，这样理解对不对？

好细致。收藏了。

看2楼就行了

　　解答：

　　1.在程序的开头要有一定的开发者、功能描述：

　　2.还需要用符号来简单的描述硬件连接，这样做的好处就是即使没有电

　　路原理图，也能在代码中看出硬件连接关系，易于程序的开发。

　　对于每个函数，在函数前都需要一段注释来描述名称、功能、入口参数、

　　出口参数，以及使用范例。如果注释描述的很清楚，那么即使不看函数的内

　　部，也能够很方便地使用函数。我们用最简单的延时函数来举例

　　4.如果注释知识代码的简单重复，将会变得毫无意义。最好的注释是简

　　介明了的点明程序的突出特征，或者阐明思路，或提供宏观的功能解释，或

　　者指出特殊之处，以帮助别人理解程序。

　　这里的注释，大部分是为了阐明思路、指出编程中容易出错的地方，以

　　帮助初学者能够理解。

　　但是我们要注意，如果最后对循环变量的注释写成这样：

　　那么这就是对代码的简单重复，对理解程序是没有任何帮助的，这就是

　　错误的注释方法。

学习学习