Comments

  • 18.1 Use /** ... */ for multi-line comments.

    1. // bad
    2. // make() returns a new element
    3. // based on the passed in tag name
    4. //
    5. // @param {String} tag
    6. // @return {Element} element
    7. function make(tag) {
    9.   // ...
    11.   return element;
    12. }
    14. // good
    15. /**
    16.  * make() returns a new element
    17.  * based on the passed-in tag name
    18.  */
    19. function make(tag) {
    21.   // ...
    23.   return element;
    24. }

  • 18.2 Use // for single line comments. Place single line comments on a newline above the subject of the comment. Put an empty line before the comment unless it’s on the first line of a block.

    1. // bad
    2. const active = true;  // is current tab
    4. // good
    5. // is current tab
    6. const active = true;
    8. // bad
    9. function getType() {
    10.   console.log('fetching type...');
    11.   // set the default type to 'no type'
    12.   const type = this.type || 'no type';
    14.   return type;
    15. }
    17. // good
    18. function getType() {
    19.   console.log('fetching type...');
    21.   // set the default type to 'no type'
    22.   const type = this.type || 'no type';
    24.   return type;
    25. }
    27. // also good
    28. function getType() {
    29.   // set the default type to 'no type'
    30.   const type = this.type || 'no type';
    32.   return type;
    33. }

  • 18.3 Start all comments with a space to make it easier to read. eslint: spaced-comment

    1. // bad
    2. //is current tab
    3. const active = true;
    5. // good
    6. // is current tab
    7. const active = true;
    9. // bad
    10. /**
    11.  *make() returns a new element
    12.  *based on the passed-in tag name
    13.  */
    14. function make(tag) {
    16.   // ...
    18.   return element;
    19. }
    21. // good
    22. /**
    23.  * make() returns a new element
    24.  * based on the passed-in tag name
    25.  */
    26. function make(tag) {
    28.   // ...
    30.   return element;
    31. }

  • 18.4 Prefixing your comments with FIXME or TODO helps other developers quickly understand if you’re pointing out a problem that needs to be revisited, or if you’re suggesting a solution to the problem that needs to be implemented. These are different than regular comments because they are actionable. The actions are FIXME: -- need to figure this out or TODO: -- need to implement.

  • 18.5 Use // FIXME: to annotate problems.

    1. class Calculator extends Abacus {
    2.   constructor() {
    3.     super();
    5.     // FIXME: shouldn’t use a global here
    6.     total = 0;
    7.   }
    8. }

  • 18.6 Use // TODO: to annotate solutions to problems.

    1. class Calculator extends Abacus {
    2.   constructor() {
    3.     super();
    5.     // TODO: total should be configurable by an options param
    6.     this.total = 0;
    7.   }
    8. }