zoukankan      html  css  js  c++  java
  • 老生常谈:注释怎么写?

    整理自知乎上我的一次回答。http://www.zhihu.com/question/20594192

    我的观点,只写说明性注释,不写功能性注释。也就是说,注释Why,而不是How和What


    类和函数多写文档注释,多少行无所谓,写在最前面,只要你是注释的Why。

    函数内部,尽量少写注释。如果你的代码需要写注释来说明他的功能,那么这段代码就需要重构,最简单的方法,最简单的方法:提取函数。这样的好处是,函数名就是注释。一个错误的观点就是 注释是给人看的,程序是给电脑看的。其实,程序是给人看的,凑巧的是,它居然可以在电脑里运行

    重构:改善既有代码的设计》一书写道:
    每当感觉需要以注释来说明点什么的时候,我们就把需要说明的东西写进一个独立函数中,并以其用途(而非实现手法)命名
    每次我给别人讲解「选择排序」、「插入排序时」,他们都觉得太难了,而且几乎每本数据结构教科书都是写了一堆代码和注释,这丝毫没有降低这个算法的难度。

    如果不写注释,而写成函数呢?

    伪代码:
    array_ordered = []
    loop_all_element(array, function(i){
      el = select(array[i+1, array.length])
      push(array_ordered, el)
      ......
    })
    1. 构建一个有序数组,初始为空,(ps:空集都是有序集)。
    2. 循环整个数组,进行如下操作:
    3. 从数组剩下的元素里面选择最小的(或最大的)
    4. 将最小元素放在有序数组的最后面(或者最前面)
    不用我多解释,你一眼就知道(即使你看不到select函数,也应该看到我加粗了“选择”二字),这是选择排序

    插入排序呢?大同小异,我就不详细写了。

    所以,文档注释,多少无所谓。函数内、类内注释,能不写,就不写

    相关阅读:千万要避免的五种程序注释方式

  • 相关阅读:
    AcWing 199. 余数之和
    AcWing 295. 清理班次
    AcWing 294. 计算重复
    Acwing 393. 雇佣收银员
    AcWing 362. 区间
    AcWing 361. 观光奶牛
    CSP-S 2019 Emiya 家今天的饭
    CSP-S 2019游记
    AcWing 345. 牛站 Cow Relays
    java 环境配置
  • 原文地址:https://www.cnblogs.com/lanzhi/p/6468138.html
Copyright © 2011-2022 走看看