Discussion on: I love to document my code. Am I doing it wrong?

[Terrance Corley]

Using clear, descriptive names for variables and functions can go a long way. That said, I'll still use comments if I feel it's necessary for readability or to understand the code with less mental effort. Most of the time I end up using comments to leave notes for myself or the team, or if something might not be immediately apparent in the code like so...

// TODO: Fix this function that is breaking item checkout
const breakingCodeFunction = () => {
  randomFunction();
};

// Add function to generate monies
const monies = () => {
  // money generating code will go here
};

[José Clovis Ramírez de la Rosa]

Good stance Corley!

Inside functions I also tend to leave code for readability, hacks, todos and even something like moment(date, 'MM/DD/YYYY').format('YYYY-MM-DD') to explain "why" that was done. People argue that comments can hurt readability but I haven't found such case yet.

[Terrance Corley]

Thanks!

Yeah I agree. If it makes it easier to understand the "why" behind the code at a quick glance- especially if it's an older project you're coming back to after some period of time, I don't see any issue with it. As some others have already said, just don't go crazy with the comments.