DEV Community: Tanisha Sabherwal

Clean Code Part 3: Comments

Tanisha Sabherwal — Thu, 15 Jul 2021 10:37:21 +0000

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.

Legal Comments: These include copyright and authorship statements at the start of source file.

// Copyright (C) 2020 by Foo Inc. All rights reserved

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 = () => ...

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.
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);

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 = () => ...

TODO comments: The comments may serve as a reminder to add or delete some code, or to clean them up in some way.
Emphasis: Comments used to emphasise the importance of some code. It shows that the code is important so that people won’t overlook it.
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.

Mumbling: Hastily plopping a comment, not paying much attention to the details does not serve much purpose.
Redundant Comments: As the name suggests, it does not serve any purpose.
Misleading comments: These comments for statements are not precise enough to be accurate.
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.

Clean Code Part 2: Functions

Tanisha Sabherwal — Mon, 05 Jul 2021 07:43:47 +0000

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

Smaller Functions

The first rule for functions is that they should be smaller and easily readable by anyone. It should have the least number of lines, each being transparently obvious. Also, avoid complex nested structures and many indent levels.

Functions should do one thing. They should do it well. They should do it only.

To ensure that the functions are doing one thing only, it is essential that all the lines inside the function belong to one level of abstraction.

Abstraction is a fundamental concept in OOPS. In brief and layman’s term and it talks about hiding the “how” part and only expose “what” to the outer world. Level of abstraction is being able to mentally grouping inside the function. In general, different “blocks” of code inside a method is a classic indicator of different level of abstractions. This means, the reader of the code now has to create a “branch” in their mental grouping to read that condition or loop block and merge back to the same level where the block ended.

Let me explain with an example.

const checkForValidOrder = (order, customer) => {
   let tax=15;
   return 
    order.status==='PLACED' &&
    order.payment==='SUCCESSFUL' &&
    order.price(1 + (tax/100)) <= customer.walletBalance
}

For the above function, there are two levels of abstraction since mathematical computation is being carried put in the last statement. This can be avoided using a small tweak.

const checkForValidOrder = (order, customer) => {
   return 
    order.status==='PLACED' &&
    order.payment==='SUCCESSFUL' &&
    generateTotalAmount(order.price, tax) <= customer.walletBalance
}

Hence, using abstraction, we are essentially hiding the “how” part and preserving the part indicating what the function does. This was a simple example with only one level of abstraction, when function tends to become bigger with many levels of abstraction, the Single Level of Abstraction (SLA) principle should be followed.

Follow the Stepdown Rule

The rule suggests that the code should be readable in a top-down narrative, descending one level of abstraction per function. It implies that the function ordering is no longer random. A caller function should always reside above the callee function.

Taking the previous example, the ordering of the functions is best as given below and not the other way around.

const checkForValidOrder = (order, customer) => {
   return 
    order.status==='PLACED' &&
    order.payment==='SUCCESSFUL' &&
    generateTotalAmount(order.price) <= customer.walletBalance
}

const generateTotalAmount = (price) => {
   let tax=15;  
   return price(1 + (tax/100));
}

Functional Arguments

Functions can be broadly classified into the following types based on the number of arguments:

Niladic(zero)
Monadic(one)
Dyadic(two)
Triadic(three)
Polyadic(more than three)

As the number of arguments for a function increases, complexity increases and it even becomes tougher from a testing point of view.

When functions need three or more arguments, most of the times, it is easier to wrap some of these arguments into a class/object of its own. This will ensure better readability.

const describeFruit = (color, name, size, price, numSeeds, type) => {
  return `${fruitName} is ${fruitColor}. It's ${fruitSize}. 
  It costs ${price}. It has ${numSeeds}. The type if 
  ${type}`;
}

The above function is too confusing to read with so many arguments. A better alternative and cleaner versionis given below.

const describeFruit = (fruit) => {
  return `${fruit.name} is ${fruit.color}. It's 
  ${fruit.size}. It costs ${fruit.price}. It has 
  ${fruit.numSeeds}. The type if ${fruit.type}`;
}

No Side Effects

Side effects are code in a function that makes changes to things that are outside the function. This can lead to unexpected changes to code outside and cause damaging mistruths.

For example, the code snippet given below should be avoid.

let numberOfBoxes = 1;
const addBoxes = () => {
  numberOfBoxes++;
}
const removeBoxes = () => {
  numberOfBoxes--;
}

Instead, do this:

const addBoxes = (numberOfBoxes) => numberOfBoxes + 1;
const removeBoxes = (numberOfBoxes) => numberOfBoxes - 1;

Ending Notes

Don't repeat yourself. They are functions for a reason.

Functions are the verbs of the code and do task to avoid any duplication. When structured correctly, functions will be shorter, well named and much readable. Hence, cleaner code.

Head over to Part 3 of the series.

Clean Code Part 1: Meaningful Names

Tanisha Sabherwal — Fri, 02 Jul 2021 10:54:32 +0000

Naming variables, functions, classes, arguments, and packages is an art not everyone understands. Those who understand, live a technical debt-free life. But few simple pointers can help you reach this goal. While most of these will sound obvious but are not completely implemented by a lot of developers. Read ahead to crack the code for writing meaningful names.

Reveal the Intent

Choosing good names takes time but saves more than it takes.

The names of variables, functions, classes should answer three broad questions:

Why it exists
What it does
How it is used

var d;  //does not reveal anything

var daysSinceCreation; // clearly reveals what it stores
var isModalOpen; // depicts the variable is a boolean
const getUserID; // denotes a function or task

Hence, focus on the simplicity of the code rather than simplicity. If a variable requires a comment, it does not reveals its intent well.

Avoid Disinformation

Avoid names which leave false clues which might obscure the meaning of code. Treat it as an honourable human, it should say what it means and mean what it says.

Don't name a group of accounts as AccountList unless it is a list.

Avoid two names with subtle differences like isAccountInformationOfUserRequired and isAccountInformationOfAdminRequired .

Make Meaningful Distinctions

Number-series naming like a1, a2, ...., an makes the code non-informative and does not reveals anything about the intention.

Another avoidable typing of naming is using noise words. Words like variable, NameString, Customer, does not reveal anything and so should be avoided.

Use Pronounceable and Searchable Names

Use words that are pronounceable so that others can use it for communication. This will enable better collaboration because "Programming is a Social Activity".

Imagine someone calling you to fix the bug and mentions using the function getmddh which gets month, date, day and hour for the post. Saying "get-M-D-D-H" is both frustrating and confusing, so rather just call it getPostTimeStamp.

Similarly names should be searchable. Single or double letter names are hard to search in a codebase. In this case Ctrl+Shift+F will no longer be at rescue and is such a bade case for giving meaningful names.

Defining Roles

Names should be such that it reveals the role of the variable, this specially is very important in languages like JavaScript everything is either a var, const or let.

Class and Object names should be a noun or noun phrase like AddressParser, WikiPage, and CustomerDetails.
Method names should be a verb or verb phase like deleteUserEntry, getUserDetails and savePostData.
Booleans should have prefix like "is" to communicate binary or 0-1 behaviour.

Add Meaningful Context

Sometimes variable names require additional data to give context to generic variable names like firstName, LastName, city, zipcode etc. In such a case adding a prefix like addrfirstName and addrLastName will denote it being a part of a larger Address class.

Scope Length Rule

Variables with shorter scope should have shorter name and vice-versa because ones with longer scope at used at multiple locations and should be descriptive.
For classes/functions, the opposite is true because the longer the scope, easier should be the access for class/functions names. It should be short and crisp however for shorter scopes, longer and descriptive names can be helpful to reveal the intent.

Ending Notes

Quoting from the book,

Any fool can write code a computer can understand, but it takes a good programmer to write code that humans can understand.

Head over to Part 2 of the series.

Clean Code by Robert C. Martin

Tanisha Sabherwal — Thu, 01 Jul 2021 18:53:08 +0000

The book opens with an infographic that clearly sums up every developer's life. He calls the skill for developing clean code as craftsmanship, best acquired in two ways:

1.Knowledge of principles, patterns, practices, and heuristics

Practice

This will be multiple-part series where I will dissect the chapters of the book and write about key takeaways that resonate with me.

Hopefully, this will enable me to get out the never-ending cycle of technical debt and increase my efficiency as a developer.

Part 1: Meaningful Names
Part 2: Functions
Part 3: Comments