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]>