Writing High‑Quality Maintainable Code: A Guide to Clear Annotations

Introduction

Good code is not always self‑explanatory; comments help developers understand complex logic, speed up onboarding, and improve collaboration.

What Are Comments?

Comments are non‑executable annotations that improve code readability. They are ignored by compilers and interpreters.

Why Add Comments?

Comments aid personal review, project hand‑over, and team efficiency, especially for intricate or legacy code.

Basic Comment Types

Shortcut keys: Windows ctrl+/ , macOS command+/

HTML

<div>
  This is a line of text
  <!-- This line is commented out -->
</div>

CSS

<style>
  div {
    /* color: #fff; */
  }
</style>

div {
  /* color: #fff; */
}

div {
  /* color: #fff; */
  /* multi‑line comment */
  // font-size: 14px; // single‑line comment
  background: #000;
}

JavaScript

Single‑line comment: // – everything after it on the same line is ignored.

Block comment: /* … */ – everything between the delimiters is ignored.

Function comment (JSDoc style):

/** … */

// Define an empty array
var ary = [];
var ary2 = []; // another empty array

/*
  This is a multi‑line comment
  Define an array
*/
var ary = [];

/**
 * Submit
 * @method onSubmit
 * @param {[Object]} data
 * @return {[Boolean]} success flag
 */
const onSubmit = (params = {}) => {
  const result = false;
  if (params) {
    result = true;
  }
  return result;
};

Special Annotation Tags

TODO – functionality to be implemented.

FIXME – code that needs fixing.

XXX – implementation questionable.

NOTE – explanation of how code works.

HACK – temporary or sub‑optimal solution.

BUG – known bug.

// TODO function not finished
// FIXME needs repair
// XXX implementation to be confirmed
// NOTE explains code purpose
// HACK needs optimization
// BUG present
const arr = [];

Tips

Why // works in .less/.scss but not in .html/.css: LESS/SCSS support both // and /* */, but the former is stripped during compilation.

Placement of single‑line comments (above vs. after code) depends on whether you comment a whole block or a specific line.

Extended Topics

IE Conditional Comments

Used to target specific versions of Internet Explorer.

<!--[if IE]>
  <link href="style.css" rel="stylesheet" />
<![endif]-->

Python and Shell Comments

# python single‑line comment
print("I could have code like this.") # another comment
''' 
Multi‑line comment block
print("This won't run.")
'''

Comment Execution Quirk

A Java single‑line comment containing the Unicode escape \u000d can break the comment line, causing the following code to execute.

public class Test {
  public static void main(String[] args) {
    String name = "Zhao Da";
    //\u000dname="Qian Er";
    System.out.println(name);
  }
}

After the escape is interpreted, the assignment becomes a separate line and prints Qian Er.

Comment‑Related VS Code Extensions

koroFileHeader – generates file‑header and function‑comment templates.

Better Comments – categorises comments (alerts, queries, TODOs, highlights).

TODO Highlight – highlights TODO, FIXME, and custom keywords.

Practical Examples

Comparing code without comments, with mediocre comments, and with well‑structured comments shows the impact on readability and maintenance.

// No comments
const noWarehouseItemIds = beSelectSkucontainer.reduce((arr, itemId) => {
  const res = Object.keys(selectRowsKey[itemId]).every(skuId => {
    const sku = selectRowsKey[itemId][skuId];
    return !!sku.warehouseCode || lodashGet(warehouses, '[0].code');
  });
  if (!res) {
    arr.push(itemId);
  }
  return arr;
}, []);

// Moderate comments
// Iterate selected SKUs to find items without stock
const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => {
  const res = Object.keys(selectRowsKey[itemId]).every(skuId => {
    const sku = selectRowsKey[itemId][skuId];
    return !!sku.stockQuantity;
  });
  if (!res) {
    arr.push(itemId);
  }
  return arr;
}, []);

// Good comments
// Iterate all selected SKUs to locate items lacking stock
const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => {
  /*
    Data format:
    selectRowsKey: {
      12345678: { // itemId
        123456: { // skuId
          name: 'sku',
        }
      }
    }
  */
  const res = Object.keys(selectRowsKey[itemId]).every(skuId => {
    const sku = selectRowsKey[itemId][skuId];
    return !!sku.stockQuantity;
  });
  // If any SKU lacks stock, add the itemId to the result array
  if (!res) {
    arr.push(itemId);
  }
  return arr;
}, []);

Conclusion

Effective comments should be concise, clear, and kept up‑to‑date; they greatly improve code comprehension and reduce future bugs.

For further discussion, leave a comment in the article’s comment section.