Clean Code Part 3: Comments

This is part 3 of the series of Clean Code By Robert C. Martin. If you haven't gone through the part 2, read here.

Most code should be self-explanatory. Code also moves around a lot. The comments don’t follow it. We can update the comments as frequently as the code, but it’s probably better to make the code clear enough so that we don’t need the comments.

The proper use of comments is to compensate for our failure to express ourself in the code.

The Good Comments

These comments are necessary and beneficial.

  1. Legal Comments: These include copyright and authorship statements at the start of source file. 
// Copyright (C) 2020 by Foo Inc. All rights reserved
  1. Informative comments: These comments are used to convey more information in addition to the code. But in most cases, they can be removed after naming things better. 
// return toggleState for accordion
const toggle = () => ....

In this case, we can just change the name to be more meaningful like:

const isAccordionOpen = () => ...

  1. Explanation of Intent: Comment beyond the implementation, reveals the intent behind the decision.
    For example: This can be used to specify why certain approach are used according to the use case.

  2. Clarification: These comments are helpful to translate some obscure arguments or return values into a more readable form.

import * as _ from "lodash";
// divide array into groups of 2
const arr = [1, 2, 3, 4, 5];
const splitArray = _.chunk(arr, 2);
  1. Warning of Consequences: Such comments are used to let people know the consequences of certain code snippet. 
// not the optimal approach to perform the task
const getTask = () => ...

  1. TODO comments: The comments may serve as a reminder to add or delete some code, or to clean them up in some way.

  2. Emphasis: Comments used to emphasise the importance of some code. It shows that the code is important so that people won’t overlook it.

  3. JSDoc comments: When writing libraries, documentation or code is served to the masses that use them. This can be done with JSDoc by writing comments in the code, which will generate documentation from it.

/**
 * Represents a Person.
 * @constructor
 * @param {string} name - The name of the person.
 * @param {number} age - The age of the person.
 */
class Person {
  constructor(name, age) {
    this.name = name;
    this.age = age;
  }
}

Bad Comments

Most comments fall into this category, which should be avoided to maintain a clean code.

  1. Mumbling: Hastily plopping a comment, not paying much attention to the details does not serve much purpose.

  2. Redundant Comments: As the name suggests, it does not serve any purpose.

  3. Misleading comments: These comments for statements are not precise enough to be accurate.

  4. Journal Comments: Comment added to the start of the module every time it is edited leads to overhead. A CHANGELOG should be used for these purposes.

Other kinds of bad comments include: Noise Comments, Positional Markers, Closing Braces Comments are our most favourite Commented-out Code.

Don't Comment bad code, rather rewrite it.

Stay tuned in, for Part 4 of the series.

14

برچسب ها:

CodenewbieCodereviewCodequalityProgramming