函数《代码整洁之道》

注释

1. 注释的作用

• 为了弥补代码表达某种意图时不够清晰的一种手段

2. 注释的缺点

• 需要写注释，就说明代码很糟糕，代码不能够清晰表达它的意思
• 注释会随着时间变得腐烂，离其描述的代码越来越远，甚至变得全部是错误的，因为程序员往往不能坚持维护注释

3. 好注释

• 不需要写注释就是最好的注释，由代码自己来阐述自己的意义

File tempDirectory = FileUtils.getTempDirectory();

• 法律信息类型的注释，例如版权及著作权声明

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

• 提供有用信息的注释，凡是能够根据注释去理解代码所代表的含义的信息，都可以称为有用信息，这个范围比较广

public static boolean contentEquals(final File file1, final File file2) throws IOException {
    final boolean file1Exists = file1.exists();
    if (file1Exists != file2.exists()) {
        return false;
    }

    if (!file1Exists) {
        // two not existing files are equal
        return true;
    }
    ...
}

• 对意图解释的注释，用于解释当前代码这么做的原因，往往是因为代码中进行了特殊处理，例如性能优化，特例处理等

if (!directory.mkdirs()) {
    // Double-check that some other thread or process hasn't made
    // the directory in the background
    if (!directory.isDirectory()) {
        final String message =
                "Unable to create directory " + directory;
        throw new IOException(message);
    }
}

• 阐释型注释，这类注释一般是由于代码结构和含义比较难以理解，因而专门进行介绍，例如算法，多参数函数等

/*
 * Implementation notes.
 *
 * This map usually acts as a binned (bucketed) hash table, but
 * when bins get too large, they are transformed into bins of
 * TreeNodes, each structured similarly to those in
 * java.util.TreeMap. Most methods try to use normal bins, but
 * relay to TreeNode methods when applicable (simply by checking
 * instanceof a node).  Bins of TreeNodes may be traversed and
 * used like any others, but additionally support faster lookup
 * when overpopulated. However, since the vast majority of bins in
 * normal use are not overpopulated, checking for existence of
 * tree bins may be delayed in the course of table methods.
 *
 * ...
 *
 */

• 警示型注释，用于警告其他程序员不要随便修改此处的代码，或者这里的代码会产生什么后果

// SimpleDateFormat is not thread safe,
// so need to create each instance independently
SimpleDateFormat df = new SimpleDateFormat("yyyy/MM/dd");
...

• TODO 列表注释，一般是由于某些原因暂时还没有做的留空，或者为了以后方便扩展留下的空门

• Javadoc 文档注释，用于介绍代码整体结构，提供公共 API 方便别人调用的注释

/**
 * An object that maps keys to values.  A map cannot contain duplicate keys;
 * each key can map to at most one value.
 *
 * <p>This interface takes the place of the <tt>Dictionary</tt> class, which
 * was a totally abstract class rather than an interface.
 *
 * <p>The <tt>Map</tt> interface provides three <i>collection views</i>, which
 * allow a map's contents to be viewed as a set of keys, collection of values,
 * or set of key-value mappings.  The <i>order</i> of a map is defined as
 * the order in which the iterators on the map's collection views return their
 * elements.  Some map implementations, like the <tt>TreeMap</tt> class, make
 * specific guarantees as to their order; others, like the <tt>HashMap</tt>
 * class, do not.
 *
 * ...
 */

4. 坏注释

• 不明确的注释，这类注释介绍不清楚，说不清楚代码的含义

// Calculate
double value = money * 50 + 100;

• 多余的注释，代码本身就很明确，不需要进行多余的注释说明

// check null
if (file == null) {
    // return if null
    return;
}

• 误导性的注释，有些注释表达不精确，什么具有误导性，注释的内容和代码存在差异
• 循规式注释，一成不变地遵循每个函数或每个变量都要有注释的规矩，会使得代码中充满注释，结构变得散乱
• 日志式注释，把注释当成日志在写，每次修改都在注释中添加修改日志。这是旧代码的写法，因为现在已经有代码版本控制系统，不再需要这种写法

/**
 * Changes log
 *
 * 2020-04-01: Fixed bug ...
 * 2020-05-01: Add a ...
 * ...
 */

• 废话注释，像讲故事一样，天马行空，不够简洁，大部分内容都和代码毫无关系
• 位置标记注释，就是用于特别标记某个代码位置的注释，没有特别价值尽量少用

// **************** Start ************** //
...
// **************** End   ************** //

• 结束括号的标记注释，一般是为了识别每个括号的意义，实际上这类注释没有必要，除非是深层嵌套结构

if (length > 0) {
    int i = 0;
    while (i < length) {
        if (i == 2) {
            ...
        } // if
        ...
    } // while
} // if

• 归属或署名，由于当前已经有代码版本控制系统，已经不需要这种注释了

// Add by xxx at 2020/04/01

• 注释的代码，其他程序员可能不敢随便删除注释的代码，因为它们可能还有用处。但是现在已经有了代码版本控制系统，代码可以找回，不需要留着被注释掉的代码

5. 注释优化

• 尽量用函数或变量来替换注释

// Check is validate
if (length > 0 && str != null && str.indexOf("s") >= 0) {
    ...
}

可以使用变量进行替换：

boolean isValid = length > 0 && str != null && str.indexOf("s") >= 0;
if (isValid) {
    ...
}

• 提炼废话较多的注释，将不相关的注释内容去掉
• 短函数不需要太多描述，选择一个好的函数名会比注释来的好