DEV Community

Cover image for Commenting Code | Good Practices
Ashish Singh Rawat
Ashish Singh Rawat

Posted on

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
..
}
Enter fullscreen mode Exit fullscreen mode

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) => {
...
}

Enter fullscreen mode Exit fullscreen mode
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

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
}
Enter fullscreen mode Exit fullscreen mode
  • Writing inappropriate description to your comment. Swearing in code. Yes, developer does that.

  • Not writing comments at all in your file.

References

Discussion (11)

Collapse
alcxander profile image
Dexter Whelan • Edited on

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.

Collapse
tiima13 profile image
Sami Puranen

Commenting Code | Good Practices

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

Collapse
joelbonetr profile image
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.

Collapse
sargalias profile image
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.

Thread Thread
joelbonetr profile image
JoelBonetR • Edited on

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 😄

Collapse
ashish9342 profile image
Ashish Singh Rawat Author

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.

Collapse
chuniversiteit profile image
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. 🙃

Anyway, speaking of good/bad comments, I’m conducting a survey on comments right now and would appreciate your input!

Collapse
devsunil profile image
Sunil Kumar Samantaray

Nice man

Collapse
ashish9342 profile image
Ashish Singh Rawat Author

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

Collapse
joelbonetr profile image
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"