目录

1 

   说明

 

                                                                                                                                                   

 

 

..................................................................................................................................................

 

 3  

2 

   注释种类

 

                                                                                                                                           

 

 

..........................................................................................................................................

 

 3  

2.1 

   重复代码

 

                                                                                                                        

 

 

.......................................................................................................................

 

 3  

2.2 

   解释代码

 

                                                                                                                        

 

 

.......................................................................................................................

 

 3  

2.3 

   代码标记

 

                                                                                                                        

 

 

.......................................................................................................................

 

 3  

2.4 

   概述代码

 

                                                                                                                        

 

 

.......................................................................................................................

 

 4  

2.5 

   代码意图说明

 

                                                                                                                

 

 

...............................................................................................................

 

 4  

2.6 

   传达代码无法表达的信息

 

                                                                                            

 

 

...........................................................................................

 

 4  

3 

   注释原则

 

                                                                                                                                           

 

 

..........................................................................................................................................

 

 4  

3.1 

   站在读者的立场编写注释

 

                                                                                            

 

 

...........................................................................................

 

 4  

3.2 

   注释无法取代良好的编程风格

 

                                                                                    

 

 

...................................................................................

 

 5  

3.3 

   好注释能在更高抽象层次上解释我们想干什么

 

                                                       

 

 

......................................................

 

 5  

4 

   规范细则

 

                                                                                                                                           

 

 

..........................................................................................................................................

 

 5  

4.1 

   文件注释规范

 

                                                                                                                

 

 

...............................................................................................................

 

 5  

4.2 

   名字空间注释规范

 

                                                                                                        

 

 

.......................................................................................................

 

 6  

4.3 

   类定义注释规范

 

                                                                                                            

 

 

...........................................................................................................

 

 7  

4.4 

   数据声明注释规范

 

                                                                                                        

 

 

.......................................................................................................

 

 8  

4.5 

   函数注释规范

 

                                                                                                                

 

 

...............................................................................................................

 

 9  

4.6 

   代码标记注释规范

 

                                                                                                      

 

 

.....................................................................................................

 

 10

   

5 FAQ

 

                                                                                                                                                  

 

 

.................................................................................................................................................

 

 11

   

5.1 

   枚举值需要注释吗？

 

                                                                                                  

 

 

.................................................................................................

 

 11

   

5.2 

   前置条件、后置条件和不变式有必要注释出来吗？

 

                                             

 

 

............................................

 

 11

   

5.3 

   写注释太耗时间怎么办？

 

                                                                                          

 

 

.........................................................................................

 

 11

   

5.4 

   有效的注释是指什么？

 

                                                                                              

 

 

.............................................................................................

 

 12

   

参考书目

 

                                                                                                                                            

 

 

...........................................................................................................................................

 

 12

   

参考工具

 

                                                                                                                                            

 

 

...........................................................................................................................................

 

 12