《重构：改善既有代码的设计》——关于代码注释的唠叨

　　这几天在看《重构：改善既有代码的设计》英文评注版这本书，以前简单看过这本书，但并不是看的特别深入。经过了一段时间的“磨练”，现在回来重新看这本书，又很多想法。

　　首先，这本书是一本好书，我感觉是软件工程师必看的一本书，而且如果有大量的编码经验看这本书会收获很大。这本书主要内容是代码重构。

　　在书中第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. 

　　书中的中文评注如下：

　　高明的程序员绝对不会将注释作为说明代码的重要手段。注释就像咖啡，适量饮用可以提精神，一旦过量，就变得过度亢奋了。

　　我个人感觉上面两端话言简意赅的说出了注释的作用，注释只是代码的一个辅助，是为了我们更好的理解代码。其实关于代码风格和注释风格，每个人都有自己的看法。我觉得都没有错，只不过每个人的看法不一样。就像我，我个人认为代码首先是给程序员看的，其次是给机器看的。因为，发明高级程序语言的目的之一就是为了让人们更好的阅读代码。变量和方法的命名就可以说明变量的作用，如果说不清楚，可以使用注释。但如果是简单易懂的变量，我觉得写注释没必要。

string personName;    // 人员姓名

　　就像上面的一行代码，我认为没必要写这个注释，不要因为写注释而去写注释。此外，在最近阅读Java源代码的时候，我发现Java源代码注释有很多特点。

    /**
     * Compares two strings lexicographically.
     * The comparison is based on the Unicode value of each character in
     * the strings. The character sequence represented by this
     * {@code String} object is compared lexicographically to the
     * character sequence represented by the argument string. The result is
     * a negative integer if this {@code String} object
     * lexicographically precedes the argument string. The result is a
     * positive integer if this {@code String} object lexicographically
     * follows the argument string. The result is zero if the strings
     * are equal; {@code compareTo} returns {@code 0} exactly when
     * the {@link #equals(Object)} method would return {@code true}.
     * <p>
     * This is the definition of lexicographic ordering. If two strings are
     * different, then either they have different characters at some index
     * that is a valid index for both strings, or their lengths are different,
     * or both. If they have different characters at one or more index
     * positions, let <i>k</i> be the smallest such index; then the string
     * whose character at position <i>k</i> has the smaller value, as
     * determined by using the &lt; operator, lexicographically precedes the
     * other string. In this case, {@code compareTo} returns the
     * difference of the two character values at position {@code k} in
     * the two string -- that is, the value:
     * <blockquote><pre>
     * this.charAt(k)-anotherString.charAt(k)
     * </pre></blockquote>
     * If there is no index position at which they differ, then the shorter
     * string lexicographically precedes the longer string. In this case,
     * {@code compareTo} returns the difference of the lengths of the
     * strings -- that is, the value:
     * <blockquote><pre>
     * this.length()-anotherString.length()
     * </pre></blockquote>
     *
     * @param   anotherString   the {@code String} to be compared.
     * @return  the value {@code 0} if the argument string is equal to
     *          this string; a value less than {@code 0} if this string
     *          is lexicographically less than the string argument; and a
     *          value greater than {@code 0} if this string is
     *          lexicographically greater than the string argument.
     */
    public int compareTo(String anotherString) {
        int len1 = value.length;
        int len2 = anotherString.value.length;
        int lim = Math.min(len1, len2);
        char v1[] = value;
        char v2[] = anotherString.value;

        int k = 0;
        while (k < lim) {
            char c1 = v1[k];
            char c2 = v2[k];
            if (c1 != c2) {
                return c1 - c2;
            }
            k++;
        }
        return len1 - len2;
    }

　　这是String类型的compareTo()函数的源代码，注释比较多，但注释比较集中，并没有影响了代码的阅读。我觉得把一些说明性的注释写在文件、类和函数的开头，这样不仅有助于阅读代码，也不会喧宾夺主。其次Java源代码的变量命名非常优美，值得我去学习。

　　这就是我对注释的一些唠叨。