There are a lot of opinions on commenting one's code.

Don't do it. Do it. It belongs in the documentation. Your code should be more declarative. It bloats the file size.

Let's knock that last one out first: 1) you shouldn't be writing a manifesto, and B) Come on, it's text. True if your comments are on par with the code, then over time, and enough users, that plain 'ol text adds up (especially if you're paying for the bandwidth!).

So, let's be realists here. First off, follow your shops' rules. But if you get to make the stylistic rules, then I'm certain that code comments will save your business more money in time saved than it would cost in bandwidth.

Documentation. Yes, in a perfect world there would be a developers document that would be maintained alongside it's matching code file. There are even tools that will extract all the correctly formatted comments in your code and output them in a document for you. That helps, but that's another thing to maintain, learn and use. I've worked in a shop that used DocBlock for commenting our PHP code. I don't know if any of our developers actually referenced the generated documentation.

I would be hard pressed to allow resources to be spent, after a product is live, on creating coding documentation (thereby removing any comments from the code base). As a Certified Scrum Master, I'd consider that an impediment for my team moving forward (to the next job, the next sprint, etc.).

This is where one's code should be more declarative. Even as some frameworks are more opinionated than others, one should use your shops style of naming declarations. For example, using camelCase, or separate_ with _underscores, or-even-with-hyphens. These steps will help your code read better, be more declarative, and lessen the need for generated documentation.

Instead of naming variables a single letter, let m = 12;, any extra characters will save resources in the long run (see above bandwidth versus file size versus developer sanity). So, let numberMonthsYear = 12 will be easily understood. True, you could comment what m stands for, but then one would probably have to scroll up in the code to help recall what that variable was. Much easier to use those extra 15 characters (even the three times in your code). I took the average file size of all my components in my latest project, and this one change in making your code more readable would add 1.8% (45 bytes) to the file size. Is that a deal breaker? I think not.

In addition to making your code more declarative, your comments should be why not how. In practice,

var fizzBuzz = function() {
  var i, output;
  for (i=1, i<101, i +=1){
    output = '';
    if ( !(i % 3) ) { output += 'Fizz'; }
    if ( !(i % 5) ) { output += 'Buzz'; }
    console.log( output || i );

should not have a comment like:

// This function will loop thru numbers of 1 to 100 and 
// and test if the current number is divisible by 3 with no remainder
// then output Fizz instead of the number, and if the number can't be
// divided evenly by three, then test if you can divide the number by 5
// with no remainder. If so, output Buzz instead of the number.
// Repeat from 1 to 100.

But rather a more valuable comment would be like:

// need to output Fizz for any number % 3
// need to output Buzz for any number % 5
// otherwise output the number

The actual coded function should be declarative enough to show that the loop will go from 1-100, so why state that in the comment? Same with the a developer if you use this operand, then it says "return the remainder from a division calculation." Truthfully, you could even remove the third line from the comment, as the code says that if both if's fail, then just output i, that is, the number.

On the flip side, please don't output that old Microsoft FrontPage97 or Macromedia Dreamweaver code. I'd rather stick pencils in my eyes (have you seen Amazon's Lore Season 1, Episode 2 Echos about Dr. Walter Feeman?...but I digress)

This was part of the problem with DocBlock, too much of the how and why of what a function or class would do.

Finally, in the real world where clients are paying the bills (regardless if that's an internal or external client) a shop needs to weigh the speed to get the product out the door and documenting all the code.


Code is as much science as it is art, There's more ways than one to skin a cat (sorry cat lovers). This is when it's good to have a comment. Another good time is when time is short:

// This could be refactored as it's not the most efficient, but deadline

Another time you may come across comments is when a developer is outlining the code:

// Get api response, deconstruct to grab the x-value
// Now add the x-value to the output
// render it out

Sometimes these stray comments will be left in. It's ok to remove these when you're in a codebase.

Lastly, comment your code where you think it's needed. Others, and not always experienced devs, will need to be in your code. Make it easy on them, as I know you've gone thru code where you wanted to rip your hair out (and a few well placed comments would have been helpful).

If I missed any, please let me know in the comments below.

P.S. Prior to the short component files that make up Meteor and React, and when I code some longer PHP files or CSS's nice to have figlet CLI help break up the code.

  .oOOOo.             o             o      O
 .O     o            O              O      o
 o                   o              o      O
 o                   o              OoOooOOo
 o         .oOo. .oOoO  .oOo.       o      O .oOo. `OoOo. .oOo.
 O         O   o o   O  OooO'       O      o OooO'  o     OooO'
 `o     .o o   O O   o  O           o      o O      O     O
  `OoooO'  `OoO' `OoO'o `OoO'       o      O `OoO'  o     `OoO'