代码整洁之道—注释

2023年11月19日 163次阅读

别给糟糕的代码加注释——重新写吧

若编程语言有足够的表达力，就不那么需要注释——也许根本不需要。

注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败，注意，失败。注释总是一种失败，我们总找不到不用注释就能表达自我的方法，总要有注释，这并不值得庆贺。每次写注释，你都该做个鬼脸，感受自己在表达能力的失败。

注释不能美化糟糕的代码，与其花时间编写解释你搞出的糟糕代码的注释，不如花时间清洁那堆糟糕的代码，写出整洁而有表达力的代码。

好注释

  1. 法律信息
    有时，公司代码规范要求编写与法律有关的注释。IDE会自动卷起这些注释

/*
 * 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.
 */

  1. 对意图的解释。
    有时候稍微解释一下，自己某段程序准备做什么操作。

  2. 提供信息的注释

// 格式化匹配的  kk.mm.ss EEE, MMM dd, yyyy
Pattern timeMatcher = Pattern.compile(
"\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*"  );

也可以把这段代码移动到某个时期和时间格式的类中，可能会更好和更清晰。

  1. 警示
    // 除非你必须要杀掉某些东西，否则则不要运行这段程序

  2. TODO 注释
    // TODO是一种程序员认为应该做，但是由于某些原因目前还没有做的工作。
    目前，大多数好IDE都提供了特别的手段来定位所有的TODO注释。

  3. 说明重要性
    // 本次操作非常重要，它去除了字符串两边的空格

如果你决定写注释，那么就花必要的时间确保写出最好的注释。

坏注释

  1. 喃喃自语

  2. 多余的注释，废话的注释。

  3. 误导性注释

  4. 循规蹈矩式注释
    例如，要求每个函数都要写javadoc，就会得到很多原本无需写注释的注释。

  5. 能用函数或变量时就别用注释。

  6. 位置标记
    有点程序员喜欢在源代码中标记某个特别的位置。少用这种无理，鸡零狗碎的注释。
    // Actions ///////////////////////////

  7. 注释掉的代码。
    有些已经不用的程序，依然被注释在哪里，有的人可能回想代码留在哪里也许会有用。但是我们现在有源代码控制系统，无需再用注释来标记，删掉即可。

最后

还是要记住，写程序不仅仅是为自己而写，考虑到读到你写的代码时的感受。不要喃喃自语，清晰的用程序语言表达自己

点赞