Opinions on comments?

Hey guys, I get so many different opinions (as with many fields in software), but this is about comments. A good friend of mine whom is a software engineer with a year of experience has the opinion that his code is self-explanatory and he doesn’t need comments. It didn’t seem like that was the right way to go about it when working with a team. I also want to avoid something like:

// Function to get element
function getElement = (element) => {
...{rest of code}...
}

Can someone give me a good example of code comments where it isn’t terrible code or at least shed your opinion on this? I am struggling to know where comments are needed, perhaps if it is a confusing/lengthy bit of code, but good code if self-explanatory? I might be overthinking all of this, but any insight would be great.

This is a terrible attitude. Your code should be clear, yes, but comments are helpful. You will want to leave comments to help future developers understand what you are doing and why.

If you look at this post: freeCodeCamp Challenge Guide: Sum All Primes Update, I have too many comments, but that is because I am trying to make more of a tutorial out of that piece of code. For production, I’d do something more like

// --------------------------------------------------------------------------------
// Brief: Sum primes from 2 to num
//
// Inputs:
//   num - upper bound to sum primes (inclusive)
// Outputs:
//  sum - sum of primes from 2 to num
// --------------------------------------------------------------------------------
function sumPrimes(num) {
  // Preallocate boolean array of odd numbers -10x perf impact vs dynamic array
  const upper = Math.floor((num - 1)/2);
  const isPrime = Array(upper).fill(true);

  // Mark multiples of each prime as false (not prime)
  for (let i = 0; i < upper; ++i)
    if (isPrime[i])
      for (let j = 3*i+3; j < upper; j+=2*i+3) // Note that number = index*2+3
        isPrime[j] = false;

  // Sum primes
  let sum = num >= 2 ? 2 : 0;
  for (let i = 0; i < upper; i++)
    if (isPrime[i])
      sum += 2*i + 3; // Again, number = index*2+3

  // Return
  return sum;
}

My comments highlight things that future developers will need to know while they improve this function, and my comments roughly break the code into some more readable chunks. I will admit that I tend to err on the side of over-commenting, but people who believe that they should never comment are simply wrong.

1 Like

Definitely, my senior at my previous job told me it is much better to over comment than not at all. I am just struggling to find that middle ground.

1 Like

For me, the minimum is

  1. Label major functions with inputs, outputs, and a brief description in the style of your team.
  2. Comment on tricky things, like strange formulas, pieces that have performance impact, etc.

On top of that, I tend to
3. Comment on larger blocks of code to leave breadcrumbs describing overall flow/purpose.

1 Like

In the project I work on professionally, it’s fairly common to see entire files with no comments. We have consistent ways that we structure files, name things, etc. We try to keep our code modular and logically organized. This means that anyone who is familiar with our codebase in general is able to read many of our files without help.

We tend to use comments:

  • When there is a twisty bit of logic that isn’t frequently used in our code
  • We want to make it clear when a section of code is for a particular circumstance
  • The reason why a bit of code is there isn’t obvious. (Comments that I see in professional projects are usually explaining why code is doing something, rather than how it is doing something.)
  • We believe that there is further work that can be done or future improvements to a section of code (TODO comments).
  • We have to use names or methods from third party libraries that we don’t find obvious/intuitive.
  • Tests. We use lots of comments in unit tests.
3 Likes

Thanks so much for this.

1 Like