写出更好的 JavaScript 代码（三）——《Clean Code》笔记

在本文是关于 写出更好的 JavaScript 代码 的第三篇文章，也是 《Clean Code》第四章与第五章的笔记，也做了 Java 到 JavaScript 的转换。

注释

• 注释是一种失败，因为你找不到不用注释就能表达自我的方法。

• 注释会撒谎；注释存在的时间越久，就离其所描述的代码越远，越来越变得全然错误。因为程序员不能坚持维护注释。

• 只有代码能忠实的告诉你它做的事。所以，尽管有时候也需要注释，但应该尽量减少注释。

• 注释不能帮你美化你搞出的糟糕的代码。与其花时间为你糟糕的代码添加注释，不如花时间清洁那堆糟糕的代码。

• 用代码来阐述

  // check to see if the employee is eligible for full benefits
  
  // bad
  if ((employee.flags && HOURLY_FLAG) && (employee.age > 65)) {
    // do something
  }
  
  // good
  if (employee.isEligibleForFullBenefits()) {
    // do something
  }
  

• 好注释

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

  // 项目经理要求这里运行缓慢，好让客户给钱优化，并得到明显的速度提升
  Thread.Seelp(2000);
  

• 坏注释

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

  • 在 GIT 等源代码版本控制系统盛行的今天，日志式的注释没有存在意义与价值，应当全部删除。

    // bad
    
    /**
    * changes (from 2011-11-11)
    * -------------------------
    * 2011-11-12: feature-1
    * 2011-11-14: feature-2
    * 2011-11-16: feature-3
    * 2011-11-18: fix-bug-1
    */
    

  • 位置标记

    // bad
    
    // Actions ////////////////////
    
    // Models ////////////////////
    

    把特定函数放在这种标记栏下面，多数时候实属无理。鸡零狗碎，理当删除 —— 特别是尾部那一长串无用的斜杠。 这么说吧。如果标记栏不多，就会显而易见。所以，尽量少用，只在贴别有用的时候用。如果滥用标记栏，就会沉默在背景噪声中，被忽略掉。

  • 直接把代码注释掉是讨厌的做法。其他人不敢删除注释掉的代码。他们会想，代码依旧放在那儿，一定有其原因，而且这段代码很重要，不能删除。

    为什么不直接删除呢？有了源代码控制系统，你的代码丢不了的。

    // bad
    const dom = document.querySelector('#dom-id');
    dom.style.display = 'inline-block';
    // dom.style.left = '10px';
    dom.style.top = '10px';
    

格式

• 代码格式很重要。代码格式不可忽略，必须严肃对待。

• 代码格式应该向报纸学习。名称应当简单且一目了然。名称本身应该足够高告诉我们是否在正确的模块中。 源文件最顶端应该给出最高层次概念和算法。细节应该往下渐次展开，直至找到源文件中最底层的函数和细节。

• 关系密切的概念应该互相靠近。除非有很好的理由，否则就不要把关系密切的概念放到不同的文件中。否则就会出现如下情况：

  你是否曾经在某个类中摸索，从一个函数跳到另一个函数，上下求索，想要弄清楚这些函数如何操作、如何互相相关，最后却被搞糊涂了。你是否曾经苦苦追索某个变量或函数的继承链条？

  如上描述的情况非常让人沮丧。因为你想要理解系统 做什么，但却花时间和精力在找到和记住那些代码碎片 在哪里。

• 若某个函数调用了另一个，就应该把它们放到一起，而且调用者应该尽可能放在被调用者上面。这样，程序就有个自然的顺序。 若坚定的遵循这条约定，读者将能够确信函数声明总会在其调用后很快出现。

以上。