[clean code Martin] comments

  1 #!/bin/bash
  2 /********************************************************
  3  * author alex
  4  * webpage http://www.cnblogs.com/alexander-chao/
  5  *******************************************************/
  6 
  7 Chapter 4: COMMENTS
  8 
  9 comments do not make up for bad code
 10     当看到堆砌在一起又非常混乱的代码，rewrite or refactoring
 11 
 12 explain yourself in your code
 13     在代码中体现你的思路，比在注释中写出你的想法要清晰，具体
 14 
 15 legal comments
 16     公司，代码使用原则，一般会需要写
 17     DO:(Martin)
 18         //Copyright (C) 2014 by zhijun All rights reserved
 19         //Realesed under blabla[protocal]
 20 
 21 provide basic infomations with a comment
 22     使用直观的例子，把一个复杂的代码行注释一下，则一定会清晰可见
 23     DO:(ME)
 24     //score = x1*y1 + x2*y2 + ... + xn*yn
 25     score += get_score(features_vec[i], i, desc);
 26     //desc = x1^By1^Ax2^By2^A...^Axn^Byn 31     desc += (target + "\1"); 33 
 34 explain your intend
 35     当代码中做了反常，或tricky的事情，一定要comment真实的意图，不然自己都不知道
 36     在干什么。
 37     TODO
 38 
 39 clarification
 40     有时使用注释，说明一下比较不容易看出来操作，或比较容易迷惑的代码行，可以直观
 41     的直接领会意义
 42     DO:(Martin)
 43     assertTrue(a.compareTo(b) == -1) // a < b
 44 
 45 warning of consequence
 46     当写的代码中，有哪些潜在的后果不明显时，要告知reader如果采用当前的函数或类或者
 47     变量时需要注意的事项。
 48     DO:(Martin)
 49     //Don‘t run unless you can wait for a long enough time
 50     function() {
 51         //这里有一个死循环
 52     }
 53 
 54 TODO comment
 55     当写代码的时候，对某些实现不满意，或对现在的实现效率不合期望希望以后有人可以改进
 56     或以后自己改进可以快速定位，也提醒其他reader注意这部分实现不是最终版本
 57     //TODO(matrix)  may change it to an file
 58     double matrix[][2] = 
 59     {
 60         { 0,    0,      0,      0,      0,     0}, 
 61         { 0,    0,      0,      0,      0,     0}, 
 62     }; 
 63 
 64 Amplification
 65     强调代码中的tricky地方,以及特殊的实现技巧，以及其潜在的侧重点
 66     DO:(Martin)
 67     string list_iterm = match.group(3).trim();
 68     //the trim is real important, It removes the starting 
 69     //spacess that can cause the item to be recognized as anothor list
 70 
 71 Javadocs 
 72     DONOT(Martin)
 73     自己写代码就不要按照javadoc那样每个函数都comment一下参数和返回值代价太大
 74 
 75 BAD COMMENTS：Martin认为大多数程序员写的大多数注释都是bad的
 76 
 77 mumbling
 78     别再代码中写废话
 79 
 80 redundant comments
 81     通篇下来都是注释，而没有什么有用的信息。会让reader形成一个ignore所有注释
 82     的阅读方式，这样使得有用的注释也等于没用了
 83 
 84 misleading comments
 85     写的注释根本不是程序要表达的意义。这TMD是最扯的，无论是自己还是别人都没有
 86     办法确定是代码实现错了，还是注释忘记改了。最终会导致reader根本没办法阅读
 87 
 88 mandated(授权) comments
 89     不是每个函数什么的都必须跟上授权信息的，但要写的话，可以按下面格式来
 90     /**
 91      * @param p1...
 92      * @param p2...
 93      * @return r...
 94      */
 95      Type function(Type X, Type Y) {}
 96 
 97 Journal comments
 98     drop it to SVN or GIT or other version control systerm!
 99 
100 noise comments
101     显而易见的就不要写了，浪费时间，还干扰合理的注释
102     DONOT:(Martin)
103     /** the name */
104     string name;
105 
106 Don‘t use a comment when you can use a function or a variable
107     可能设置一些变量会显得代码臃肿。但是如果这样设置可以避免混淆，歧义，以及
108     去上下文寻找答案的话。那么就do it
109 
110 position maker
111     if you think it may lead you to segment the code, then do it. but don‘t use
112     too much
113 
114 closing brace comment
115     这个我以前从来没有用过，不过Martin说了，如果你需要用括号注释的时候，说明你程
116     序的深度过大，应该考虑refactoring or extract it into a function。
117     如果的确是括号层数太多了，就用closing brace吧。
118     DO:(Martin)
119     if (expr) {
120         while (expr) {
121             for (expr) {
122                 //do something 
123             } // for
124         } // while
125     } // if
126 
127 attributions and bylines
128     again drop it to svn and git blabla
129 
130 commented out code
131     尽量不要出现被注释掉的代码块，考虑remove或者refine它。当然我觉得要真有那么几段
132     也还OK，只是要注意别用多了
133 
134 HTML comments
135     drop it
136 
137 nonlocal comments
138     别在一个地方，写关乎全局或者其他片段的注释。没人会翻十多页去查有没有那个var或者func
139 
140 too much information
141     avoid
142 
143 function header    
144     别像javadocs那样极端，有必要说明一下的再说明。否则ignore