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 comments101     显而易见的就不要写了，浪费时间，还干扰合理的注释102     DONOT:(Martin)103     /** the name */104     string name;105 106 Don‘t use a comment when you can use a function or a variable107     可能设置一些变量会显得代码臃肿。但是如果这样设置可以避免混淆，歧义，以及108     去上下文寻找答案的话。那么就do it109 110 position maker111     if you think it may lead you to segment the code, then do it. but don‘t use112     too much113 114 closing brace comment115     这个我以前从来没有用过，不过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             } // for124         } // while125     } // if126 127 attributions and bylines128     again drop it to svn and git blabla129 130 commented out code131     尽量不要出现被注释掉的代码块，考虑remove或者refine它。当然我觉得要真有那么几段132     也还OK，只是要注意别用多了133 134 HTML comments135     drop it136 137 nonlocal comments138     别在一个地方，写关乎全局或者其他片段的注释。没人会翻十多页去查有没有那个var或者func139 140 too much information141     avoid142 143 function header    144     别像javadocs那样极端，有必要说明一下的再说明。否则ignore