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

什么也比不上放置良好的注释来的有用。什么也不会比乱七八糟的注释更有本事搞乱一个模块。什么也不会比陈旧、提供错误信息的注释更有破坏性。

  • 注释总是一种失败。我们总无法找到不用注释就能表达自我的方法,所以总要有注释,这并不值得庆贺。
  • 注释存在的时间越久,就离其所描述的代码越远,越来越变得全然错误。原因很简单,程序员不能坚持维护注释。
  • 程序员应当负责将代码注释保持在可维护、有关联、精确的高度。
  • 尽管有时也需要注释,我们也该多花信息尽量减少注释量。

注释不能美化糟糕的代码

  • 写注释的常见动机之一是糟糕的代码的存在。
  • 带有少量注释的整洁而有表达力的代码,要比带有大量注释的零碎而复杂的代码像样得多。

用代码来阐述

在这里插入图片描述

好注释

  • 有写注释是必须的,也是有利的。

法律信息: )
公司代码规范要求编写与法律有关的注释。
在这里插入图片描述

提供信息的注释:
在这里插入图片描述

  • 更好的方式是尽量利用函数名称传达信息。

对意图的解释:

  • 有时,注释不仅提供了有关实现的有用信息,而且还提供了某个决定后面的意图。

阐释:

  • 有时,注释把某些晦涩难懂的参数或返回值的意义翻译为某种可读形式,也会是有用的,更好的方法是尽量让参数或返回自身就足够清楚。
    在这里插入图片描述

警示:

  • 有时,用于警告其他程序员会出现的某种后果的注释也是有用的。

TODO注释:

  • 有时,有理由用//TODO 形式在源代码中放置要做的工作列表。
  • TODO是一种程序员认为要做的,但由于某些原因还没做的工作。

放大:
注释可以用来放大某种看来不合理之物的重要性。

公共API中的javadoc:

  • 没有什么比良好描述的公共API更有用和令人满意的了。
  • 如果你在编写公共API,就该为它编写良好的javadoc

坏注释

  • 大多数注释都输入此类。通常,坏注释都是糟糕的代码的支撑或接口,或者对错误决策的修正,基本上等于程序员自说自话。

喃喃自语:

  • 如果你决定写注释,就要花必要的实践确保写出最好的注释。
  • 任何迫使读者查看其他模块的注释,都没能与读者沟通好,不值所费。

多余的注释:
4-1展示的简单函数,其头部位置的注释全属多余。都这段注释花的时间没准比读代码花的时间还要长。
在这里插入图片描述
误导性注释:

循规式注释:

  • 每个函数都要注释,或者每个变量都要注释的规矩是愚蠢可笑的。
  • 这类注释徒然让代码变得散乱,满口胡言,令人迷惑不解。
  • 这类废话只会搞乱代码,有可能误导读者。

日志式注释:
在这里插入图片描述

  • 很久以前,在模块开始处创建并维护这些记录还算有道理。那时,我们还没有源代码控制系统可用。

废话注释:

  • 有时,你会看到纯然是废话的注释。
    在这里插入图片描述
    在这里插入图片描述
    在这里插入图片描述
  • 这类注释废话连篇,我们都学会了视而不见。
  • 与其纠缠于毫无价值的废话注释,程序员应该意识到,他的挫败感可以由改进代码结构而消除。
  • 用整理代码的决心替代创造废话的冲动吧。你会发现自己成为更优秀、更快乐的程序员。

可怕的废话:

  • javadoc可能是废话。
    在这里插入图片描述
  • 再仔细读读这些注释,你是否发现了剪切-粘贴错误?

能有函数或变量时就别用注释:
在这里插入图片描述
位置标记:

  • 有时,程序员喜欢在源代码中标记某个特别位置
    在这里插入图片描述
  • 如果标记栏不多,就会显而易见。所以,尽量少用标记栏,旨在特别有价值的时候用。

括号后面的注释:

  • 有时,程序员会在括号后面放置特殊的注释。
    在这里插入图片描述

归属与署名:

  • 源代码控制系统非常善于记住是谁在何时添加了什么。
  • 源代码控制系统是这类信息最好的归属地。

注释掉的代码:

  • 直接把代码注释掉是最讨厌的做法,别这么干!
    在这里插入图片描述
  • 其他人不敢删掉注释掉的代码。
  • 注释掉的代码堆积再一起,就像破酒瓶底的渣滓一般。
  • 20世纪60年代,曾经有那么一段时间,注释掉的代码可能有用。但是我们已经拥有优良的源代码控制系统如此之久,这些系统可以为我们记住不要的代码。
  • 删掉即可,他们丢不了!

HTML注释:

  • 源代码注释中的HTML标记是一种厌恶。

非本地信息:

  • 假如你一定要写注释,请确保它描述了离它最近的代码。

信息过多:

  • 别在注释中添加有趣的历史性话题或者无关的细节描述。

不明显的联系:

  • 注释及其描述的代码之间的兰溪应该显而易见。
  • 如果你不嫌麻烦要写注释,至少让读者能看着注释和代码,并且理解注释所谈何物。

函数头:

  • 短函数不需要太多描述。

非公共代码中的javadoc:

展开阅读全文

Python数据分析与挖掘

01-08
92讲视频课+16大项目实战+源码+¥800元课程礼包+讲师社群1V1答疑+社群闭门分享会=99元   为什么学习数据分析?       人工智能、大数据时代有什么技能是可以运用在各种行业的?数据分析就是。       从海量数据中获得别人看不见的信息,创业者可以通过数据分析来优化产品,营销人员可以通过数据分析改进营销策略,产品经理可以通过数据分析洞察用户习惯,金融从业者可以通过数据分析规避投资风险,程序员可以通过数据分析进一步挖掘出数据价值,它和编程一样,本质上也是一个工具,通过数据来对现实事物进行分析和识别的能力。不管你从事什么行业,掌握了数据分析能力,往往在其岗位上更有竞争力。    本课程共包含五大模块: 一、先导篇: 通过分析数据分析师的一天,让学员了解全面了解成为一个数据分析师的所有必修功法,对数据分析师不在迷惑。   二、基础篇: 围绕Python基础语法介绍、数据预处理、数据可视化以及数据分析与挖掘......这些核心技能模块展开,帮助你快速而全面的掌握和了解成为一个数据分析师的所有必修功法。   三、数据采集篇: 通过网络爬虫实战解决数据分析的必经之路:数据从何来的问题,讲解常见的爬虫套路并利用三大实战帮助学员扎实数据采集能力,避免没有数据可分析的尴尬。   四、分析工具篇: 讲解数据分析避不开的科学计算库Numpy、数据分析工具Pandas及常见可视化工具Matplotlib。   五、算法篇: 算法是数据分析的精华,课程精选10大算法,包括分类、聚类、预测3大类型,每个算法都从原理和案例两个角度学习,让你不仅能用起来,了解原理,还能知道为什么这么做。
©️2020 CSDN 皮肤主题: 大白 设计师: CSDN官方博客 返回首页
实付0元
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值