《代码整洁之道》（4）注释 |
您所在的位置：网站首页 › java代码整洁 › 《代码整洁之道》（4）注释 |
|
注释不能美化糟糕的代码
带有少量注释的整洁而富有表达力的代码，要优于带有大量注释的零碎而复杂的代码。 与其花时间解释糟糕的代码，不如花时间清洁那堆糟糕的代码。 用代码来阐述当代码本身足以解释其行为时，就应该用代码来阐述意图，如： 用 if (employee.isEligibleForFullBenefits()) 复制代码代替 // Check to see if the employee is eligible for full benefits if ((employee.flags & HOURLR_FLAG) && employee.age > 65) 复制代码只需要创建一个描述与注释所言同一事物的函数，就可以用代码解释大部分的意图。 好注释唯一真正好的注释是想办法不去写的注释，但是有些注释是必须的，也是有利的，值得一写。 与法律有关的注释，它不应该是具体条款或合同，而是指向一份标准许可或其它外部文档 提供信息的注释，如解释抽象方法的返回值，当然，更好的方式是尽量利用函数名称传达信息 对意图的解释，可以让其他程序员知道你想干什么，有助于别人理解代码或是给出更好的解决方案 阐释，翻译某些晦涩难懂的参数或返回值的意义 警示，用于警告其他程序员会出现的某种后果 TODO注释，它是一种应该做，但是由于某些原因还没有做的工作 放大，用来放大某种看来不合理之物的重要性 公共API中的Javadoc 坏注释大多数的注释基本都属于此类，反映了糟糕的代码支撑或接口，或者对错误决策的修正。 喃喃自语般的注释，如果觉得应该或者因为过程需要就添加注释，那就是无谓之举，如果决定写注释，那就要花必要的时间确保写出最好的注释 多余的注释，这种注释并不能比代码本身提供更多的信息，它没有证明代码的意义，也没有给出代码的意图或逻辑，有时它甚至不如代码精确 误导性的注释，尽管初衷可嘉，有时候还是会写出不够精确、有误导嫌疑的注释 循规式注释，不可能让每个函数或变量都有注释，因为这会让代码变得散乱 日志式注释，由于源代码控制系统（git）的广泛应用，这种编辑代码时记录的日志只会让模块变得凌乱不堪，应当全部删除 废话注释，比如给无参构造增加一个Default Constructor注释，或者给dayOfMonth增加一个The day of the Month注释 可怕的废话，Javadoc也可能是废话，某知名开源库甚至有复制-粘贴错误 能用函数或变量时就别用注释 位置标记，有些程序员喜欢在源代码中标记某个特别位置，这种做法实属无理 括号后面的注释，这对于含有深度嵌套结构的长函数可能有意义，然而更好的方式应该是缩短函数 归属与署名，这类信息最好的地方应该是源代码控制系统（git），而不是写在注释里 注释掉的代码，同上，历史代码可以在源代码控制系统中找到，不需要把注释掉的代码堆积在一起，在源代码中删掉它们是最好的选择 HTML注释，IDE中的注释和代码本来易于阅读，却因为HTML注释的存在而变得难以阅读 非本地信息，写注释时最好靠近它所描述的代码，一来方便阅读，二来方便修改代码时同步修改注释 信息过多，不要添加历史性话题或者无关的细节描述 不明显的联系，不要怕麻烦少写注释，注释的作用是解释未能自行解释的代码，如果注释本身还需要解释，那就说明注释写得有问题 函数头，为只做一件事的短函数选个好名字，通常要好于写函数头注释 非公共代码中的Javadoc，代码如果不打算作公共用途，就没必要生成Javadoc |
今日新闻 |
推荐新闻 |
| CopyRight 2018-2019 办公设备维修网 版权所有 豫ICP备15022753号-3 |