DEV Community

On Comments in Code

Henrik Warne on June 15, 2021

I used to think that I didn’t need comments if I wrote self-documenting code. However, I have realized that I do write comments, and that I find th...
Read full post
Collapse
 
costinmanda profile image
Costin Manda •

Like you, I live in the borderlands, hunted by both comment style purists and descriptive code zealots.

There are code comments that cannot be explained by variable or method names, like the reason why something was done (or changed).

Compare these two versions and tell me which you find more useful:

// X and Y should not be enhanced (PBI 12345)
if (/^(X|Y)/.test(item)) {
  return;
}
Enter fullscreen mode Exit fullscreen mode

and (where the PBI for this should be searched in source control history)

if (shouldNotBeEnhanced(item)) {
  return;
}
...
function shouldNotBeEnhanced(item) {
 return isItemAnXOrAnY(item));
}

function isItemAndXOrAnY(item) {
  return /^(X|Y)/.test(item);
}
Enter fullscreen mode Exit fullscreen mode

Perhaps this example (simplification of code I wrote today) is just proof of my laziness, but I prefer version 1 both as a writer and as a reader.