[Clean Code Martin] Comments

1#!/bin/Bash2 /********************************************************3 * Author Alex4 * Webpage http://www.cnblogs.com/alexander-chao/5  *******************************************************/6 7Chapter4: COMMENTS8 9Comments DoNot do up forBad codeTen when you see the code that's piled up and very confusing, rewrite or refactoring One  AExplain yourselfinchYour code - reflect your ideas in the code, rather than writing your ideas in the comments, be clear, specific -  the Legal Comments - Company, code use principle, generally will need to write - Do : (Martin) -         //Copyright (C) by Zhijun All rights reserved +         //realesed under blabla[protocal] -  + provide basic infomations with a comment A with an intuitive example, a complex line of code is commented out, it will be clearly visible at Do : (ME) -     //score = x1*y1 + x2*y2 + ... + xn*yn -Score + =Get_score (Features_vec[i], I, DESC); -     //desc = X1^by1^ax2^by2^a...^axn^byn toDesc + = (target +"\1"); -  the explain your intend * The contemporary code does the unusual, or the tricky thing, must comment the real intention, otherwise I do not know $ are doing. Panax Notoginseng TODO -  the Clarification + Sometimes you can use comments to show that the comparison is not easy to see, or more easily confusing lines of code, it is intuitive to A the direct meaning of understanding the Do : (Martin) +Asserttrue (A.compareto (b) = =-1)//a < b -  $ warning of Consequence $ when writing code that has potential consequences that are not obvious, tell reader to use the current function or class or - variables to be aware of.  - Do : (Martin) the     //Don ' t run unless you can wait for a long enough time - function () {Wuyi         //There's a dead loop here . the     } -  Wu TODO Comment - when writing code, not satisfied with some implementations, or the current implementation of the efficiency is not expected to hope that someone can improve About or later self-improvement can be quickly positioned, but also reminds other reader note that this part of the implementation is not the final version $     //TODO (Matrix) may change it to an file -     Doublematrix[][2] = -     { -{0,0,0,0,0,0},  A{0,0,0,0,0,0},  +     };  the  - Amplification $ emphasize the tricky place in the code, as well as the special implementation techniques, and their potential focus the Do : (Martin) the     stringList_iterm = Match.group (3). Trim (); the     //The trim is real important, It removes the starting the     //spacess that can cause the item to be recognized as Anothor list -  in Javadocs the DONOT (Martin) the If you write your own code, do not follow javadoc, and every function is comment. Parameters and return values are too expensive About  the Bad Comments:martin thinks most of the notes written by most programmers are bad. the  the mumbling + stop writing nonsense in the code. -  the Redundant CommentsBayi The entire article is a comment, and there is no useful information. will let reader form a ignore all comments the Way of reading, so that useful annotations are useless. the  - Misleading Comments - writing a comment is not the meaning of the program to be expressed at all. This TMD is the most ridiculous, neither himself nor anyone else. the The way to determine whether the code implementation is wrong, or the comment forgot to change. Eventually, the reader won't be able to read . the  the mandated (authorized) Comments the not every function or anything must keep up with the authorization information, but to write, you can follow the format to -     /** the * @param p1 ... the * @param p2 ... the * @return R ...94      */ the type function (type X, type Y) {} the  the Journal Comments98Drop it to SVN or GIT or other version control systerm! About  - Noise Comments101 The obvious is not to write, waste time, but also interfere with reasonable comments102 DONOT: (Martin)103     /** The name*/104     stringname; the 106Don'T use a comment if you can use a function or a variable107 Some variables can be set to appear bloated code. But if this is set up to avoid confusion, ambiguity, and108 go to the context to find the answer. So just do it109  the position maker111     ifYou think it may leads you to segment the code and then DoIt. But Don'T use the Too much113  the closing Brace Comment the I've never used this before, but Martin said that if you need to comment in parentheses, it means the the depth of the order should be considered refactoring or extract it into a function. 117 If it is true that there are too many brackets, use closing brace. 118 Do : (Martin)119     if(expr) { -          while(expr) {121              for(expr) {122                 //Do something123}// for124}// while the}//if126 127 attributions and Bylines - again drop it to SVN and git blabla129  theCommented outCode131 try not to show the code block that is commented out, consider remove or refine it. Of course, I think it's going to be a few paragraphs . the It's OK, just be careful not to use too much.133 134 HTML Comments135 Drop It136 137 nonlocal Comments138 don't write a comment about a global or other fragment in one place. No one's going to go over 10 pages to find out if that's Var or func.139  $ Too Much information141 Avoid142 143 function Header144Do not be as extreme as javadocs, it is necessary to explain the further explanation. otherwise ignore

[Clean Code Martin] Comments