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函数,也应该看到我加粗了“选择”二字),这是选择排序

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

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

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

  • 相关阅读:
    CODEVS——T 2618 核电站问题
    Spring使用AspectJ注解和XML配置实现AOP
    oracle存储过程
    oracle什么时候需要commit
    短信发送接口被恶意访问
    JAVA内存模型
    构造函数,静态代码块,构造代码块
    mybatis缓存
    volatile和synchronized
    利用反射创建对象必须要显式的声明构造方法吗?
  • 原文地址:https://www.cnblogs.com/lanzhi/p/6468138.html
Copyright © 2011-2022 走看看