Commenting Code | Good Practices

Imagine, you have joined a new company and given access to their source code. Now it's your sole responsibility to maintain the code and you cannot go to the guy who has written this code.

As a developer, regardless of speciality, we tend to spend more time on reading others' code. Writing comments can help other developers understand the complex logic you were thinking while building it.

Here are some tips that can be used while writing comments.

Single line comments

• This starts with // and then the description of the code
• It’s a good idea to comment code that someone else might consider unneeded.

// execute only if array has some value
if(arr.length) { // inline comment
..
}

Multiline Comments

• These comments are generally written when you have developed a complex feature.
• It helps in documenting the project.
• It starts with a blank line starting with /**
• each line starts with *
• Ends with with a blank line starting with */

/**
 * @description This function generates the button required for Action Bar
 * @author Ashish
 * @param { Function } t => translation function
 * @param { Object } history => contains previous state
 * @param { Function } print => property passed from parent to print
 * @returns { Array } buttons array of Objects
 * @see {@link https://stackoverflow.com/users/5282407/ashish-singh-rawat }
 * @todo Performance optimisation, removing multiple loops
 * * BELOW ARE SOME MORE META DATA, that can be used
 * @argument @async @borrows @class @classdesc @constant
 * @constructor @copyright @default @deprecated @emits
 * @enum @event @example @extends @external @field @file
 * @fileoverview @fires @function @generator @global
 * @hideconstructor @host @ignore @implements @inheritdoc @inner
 * @instance @interface @kind @lends @license @listens @member @memberof
 * @method @mixes @module @name @namespace @override @param @private @property
 * @protected @public @readonly @returns @see @since @static @summary @template
 * @this @throws @tutorial @type @typedef @var @variation @version @virtual 
 * @yields 
 **/
export const getButtons = (t, history, print) => {
...
}

Adding a metadata

• Add a preface/ description to your comment, keep it short and what it does. No one wants to read a novel.
• parameter or arguments, it is accepting and the type of it
• Author this tells who has written this
• return what exactly the function is returning
• link a reference to other web link
• todo if have written a hackfix, or you want to change the code in later stage
• There are other metadatas, which you can use. Just @ in your multi comments will the rest
• Eg: example, methodof, private, public, protected ...

Note:

type to be in uppercase Boolean, Object.

Now if somebody is using your functions with comments it will also help them write their code. Eg:

Don'ts

• Writing comments for each line. Yes I have seen code where comments are written for each line or self explanatory.

Compnent.propTypes = {
  /** translation function */
  translation: PropTypes.func,
  /* history received as props for navigation purpose */
  history: PropTypes.object,
  /** data from graphql response */
  data: PropTypes.object
}

• Writing inappropriate description to your comment. Swearing in code. Yes, developer does that.

• Not writing comments at all in your file.

References

• There are multiple good libraries that have good comments like lodash, React, Angular.
• Please to refer their comment style for more.
• Funny comments

Comments

[Dexter Whelan]

having taken over many types of code systems in the past I can confirm with 100% certainty some of the best most appropriate comments I've ever seen in a code base have been littered with swear words and have been on every other line.

[Sami Puranen]

Commenting Code | Good Practices

Do not comment the code.
This is reasoned excample in book
 'Clean code' by Robert C. Martin

[JoelBonetR 🥇]

As senior dev/tech lead I would prefer to see, at least, @params and @return to avoid others loosing them time reading code that they'll forget in like 2 minutes.

The rule about not commenting the code is simply bullshit and needs a fallback which is "document your features and usecases" (which must be consultant's competence and not devs one) if you don't have one or another it will be harder to maintain the software even being 100% clean code.

[Spyros Argalias]

Completely agree. I consider "comments as documentation" good. They make the project easier for developers to work with because glancing over the documentation is much faster and easier than reading through the code.

On the other hand, I think "Inline commenting" is bad. That's used when the code needs explaining because it's difficult to understand.

They're different things.

[JoelBonetR 🥇]

Sure! I'm talking just about the usual documentation above each function/method that defines the required information to work with this provided function/method without making you read the current implementation 😄

[Ashish Singh Rawat]

Thanks I will check this book.

We need to have a clean code for not commenting. There can be chances where you think you can improve the performance and doesn't have the time to think for best solution.

[Chun Fei Lung]

I once also worked on a codebase where developers only added comments to functions “because it creates a nice visual space between them”, which (depending on your perspective) can be either a good or a bad reason. 🙃

[Sunil Kumar Samantaray]

Nice man

[Ashish Singh Rawat]

Thanks, hope you liked the article and try to follow some of it.

[JoelBonetR 🥇]

Once I saw a language dependant feature that at the end had a fallback to Zimbabwe with a comment saying "equivalent to null. [companyName] will not have clients from zimbabwe anyway"