首页 > 代码库 > 《重构:改善既有代码的设计》——关于代码注释的唠叨
《重构:改善既有代码的设计》——关于代码注释的唠叨
这几天在看《重构:改善既有代码的设计》英文评注版这本书,以前简单看过这本书,但并不是看的特别深入。经过了一段时间的“磨练”,现在回来重新看这本书,又很多想法。
首先,这本书是一本好书,我感觉是软件工程师必看的一本书,而且如果有大量的编码经验看这本书会收获很大。这本书主要内容是代码重构。
在书中第3章中有这样一段话是用来描述代码注释的:
A good time to use a comment is when you don‘t know what to do. In addition to describe what is going on,comments can indicate areas in which you aren‘t sure. A comments is a good place to say why you did something.
书中的中文评注如下:
高明的程序员绝对不会将注释作为说明代码的重要手段。注释就像咖啡,适量饮用可以提精神,一旦过量,就变得过度亢奋了。
我个人感觉上面两端话言简意赅的说出了注释的作用,注释只是代码的一个辅助,是为了我们更好的理解代码。其实关于代码风格和注释风格,每个人都有自己的看法。我觉得都没有错,只不过每个人的看法不一样。就像我,我个人认为代码首先是给程序员看的,其次是给机器看的。因为,发明高级程序语言的目的之一就是为了让人们更好的阅读代码。变量和方法的命名就可以说明变量的作用,如果说不清楚,可以使用注释。但如果是简单易懂的变量,我觉得写注释没必要。
1 string personName; // 人员姓名
就像上面的一行代码,我认为没必要写这个注释,不要因为写注释而去写注释。此外,在最近阅读Java源代码的时候,我发现Java源代码注释有很多特点。
1 /** 2 * Compares two strings lexicographically. 3 * The comparison is based on the Unicode value of each character in 4 * the strings. The character sequence represented by this 5 * {@code String} object is compared lexicographically to the 6 * character sequence represented by the argument string. The result is 7 * a negative integer if this {@code String} object 8 * lexicographically precedes the argument string. The result is a 9 * positive integer if this {@code String} object lexicographically 10 * follows the argument string. The result is zero if the strings 11 * are equal; {@code compareTo} returns {@code 0} exactly when 12 * the {@link #equals(Object)} method would return {@code true}. 13 * <p> 14 * This is the definition of lexicographic ordering. If two strings are 15 * different, then either they have different characters at some index 16 * that is a valid index for both strings, or their lengths are different, 17 * or both. If they have different characters at one or more index 18 * positions, let <i>k</i> be the smallest such index; then the string 19 * whose character at position <i>k</i> has the smaller value, as 20 * determined by using the < operator, lexicographically precedes the 21 * other string. In this case, {@code compareTo} returns the 22 * difference of the two character values at position {@code k} in 23 * the two string -- that is, the value: 24 * <blockquote><pre> 25 * this.charAt(k)-anotherString.charAt(k) 26 * </pre></blockquote> 27 * If there is no index position at which they differ, then the shorter 28 * string lexicographically precedes the longer string. In this case, 29 * {@code compareTo} returns the difference of the lengths of the 30 * strings -- that is, the value: 31 * <blockquote><pre> 32 * this.length()-anotherString.length() 33 * </pre></blockquote> 34 * 35 * @param anotherString the {@code String} to be compared. 36 * @return the value {@code 0} if the argument string is equal to 37 * this string; a value less than {@code 0} if this string 38 * is lexicographically less than the string argument; and a 39 * value greater than {@code 0} if this string is 40 * lexicographically greater than the string argument. 41 */ 42 public int compareTo(String anotherString) { 43 int len1 = value.length; 44 int len2 = anotherString.value.length; 45 int lim = Math.min(len1, len2); 46 char v1[] = value; 47 char v2[] = anotherString.value; 48 49 int k = 0; 50 while (k < lim) { 51 char c1 = v1[k]; 52 char c2 = v2[k]; 53 if (c1 != c2) { 54 return c1 - c2; 55 } 56 k++; 57 } 58 return len1 - len2; 59 }
这是String类型的compareTo()函数的源代码,注释比较多,但注释比较集中,并没有影响了代码的阅读。我觉得把一些说明性的注释写在文件、类和函数的开头,这样不仅有助于阅读代码,也不会喧宾夺主。其次Java源代码的变量命名非常优美,值得我去学习。
这就是我对注释的一些唠叨。