[学习笔记] 《代码整洁之道》（三）

最新推荐文章于 2024-06-25 16:06:44 发布

minus87

最新推荐文章于 2024-06-25 16:06:44 发布

阅读量174

点赞数

分类专栏：学习笔记

本文链接：https://blog.csdn.net/minus87/article/details/83686725

版权

学习笔记专栏收录该内容

8 篇文章 0 订阅

订阅专栏

[学习笔记] 《代码整洁之道》—第4章注释

什么也比不上放置良好的注释来的有用！
什么么也比不上乱七八糟的注释更有本事捣乱一个模块！
什么也不会比陈旧、提供错误信息的注释更有破坏性！
注释的恰当用法是弥补我们代码表达意图时的失败。
- 注释总是一种失败；
- 注释会撒谎：主食存在的时间越久，就离所描述的代码越远，越来越变得全然错误。
程序员应当负责将注释保持在可维护、有关联、和精确的高度。
- 不准确的注释要比没有注释还糟糕。
唯一真实的就是代码！
- 尽管有时需要注释，我们也该多花心思尽量减少注释。

注释不能美化糟糕的代码

写注释的常见动机之一就是糟糕的代码的存在。
- 带有少量注释的整洁而又表达力的代码，要比带有大量注释的零碎而复杂的代码像样得多。
- 与其花时间编写解释糟糕代码的注释,不如花时间清洁那堆糟糕的代码。

用代码来阐述

有时，代码本身不足以解释其行为

有的程序员认为：代码很少 —> 如果有的话 —> 能做好解释工作（错误！！！）

// Check to see if the employee is eligible for full benefits
if((employee.flags & HOURLY_FLAG) &&
   (employee.age >65))

// 或许你更愿意看到这个
if(employee.isEligibalForFullBenefits())

只要多花一点时间，就能用代码解释你大部分意图。

好注释

有些注释是必须的，也是有利的。

唯一真正好的注释就是想办法不去写的注释。

法律信息：版权及著作权声明
```
// Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.
// Released under the terms of the GUN General Public License version 2 or later.
```
- 这类注释不应该是合同或法典。
- 只要有可能，就只想一份标准许可或其他外部文档，而不是把所有条款放到注释中。
提供基本信息
- 这类注释有时管用，但更好的方式是尽量用函数名称传达信息。
不仅提供了有关实现的有用信息，还提供了某个决定后面的意图。
把某些晦涩难明的参数或者返回值的意义翻译为某种可读形式。
- 更好的方式是尽量让参数或返回值滋生足够清楚。
- 如果参数或返回值是某个标准库的一部分，或是你不能修改代码，帮助阐述其含义的代码就会有用。
警告其他程序许愿出现某种后果
用//TODO 形式在源代码中放置要做的工作列表。
放大某种开来不合理之物的重要性。
没有比被良好描述的公共API更有用和令人满意的了。

坏注释

坏注释都是糟糕的代码的支撑和借口，或者对错误决策的修正，基本上等于程序员的自说自话。

如果只是因为你觉得应该或者过程需要就添加注释，那就是无谓之举。
- 如果你决定写注释，就要花必要的时间确保写出最好的注释。
多余的注释
- 不能比代码本身提供更多的信息
- 没有证明代码的意义
- 没有给出代码的意图或逻辑
误导性注释
循规式注释
日志式注释
废话注释

可怕的废话

/** The name **/
private String name;

/** The version **/
private String version;

能用函数或者变量时就别用注释

// does the module from the global list <mod> depend on the
// subsystem we are part of?
if(smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))

改成没有注释的版本如下

ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if(moduleDependees.contains(ourSubSystem))

位置标记

括号后面的注释

try{
    /* ... */
    /* ... */
    while(1){
        /* ... */
        /* ... */
        /* ... */
    } //while
    /* ... */
    /* ... */
} //try
catch{
    /* ... */
} //catch