Commenting Code | Good Practices
Tags: programming, javascript, codequality, productivity
Published: 2021-09-26 15:43:05

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.

```javascript
// 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 */


```javascript

/**
 * @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:


![commenting code | good practices](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9m24e48jzscmn13vmqoc.PNG)


###Don'ts
* Writing comments for each line. Yes I have seen code where comments are written for each line or self explanatory.

```javascript
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](https://www.vidarholen.net/contents/wordcount/#fuck*,shit*,crap*,bastard,penguin,idiot) 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](https://lodash.com/docs/4.17.15), [React](https://github.com/facebook/react), [Angular](https://github.com/angular/angular).
* Please to refer their comment style for more.
* [Funny comments](https://stackoverflow.com/questions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encountered?answertab=votes#tab-top)