
Stop Writing Code Comments - dutchbrit
https://medium.com/@bpnorlander/stop-writing-code-comments-28fef5272752
======
jaabe
I think this is horrible advice, and while it’s anecdotal I’ve seen no reason
to suggest that not writing code comments leads to higher quality code.

I once managed a developer who at a time could have written this very
blogpost. He was also a big fan of the solid principles, and I think he
generally wrote good code. I actually also agree with parts of the article. If
you name your properties and functions in a reasonable way, then you don’t
need a comment telling the future what you put in firstName on an employee
object or what getEmployees() does. When it comes to business logic and
intend, however, you need to help the future. My developer learned this the
hard way when some business logic changed and he had to fix a system he had
written a couple of years earlier. Suddenly the once so clear code wasn’t
clear anymore, and he had to spent a week reintroducing himself to exactly
what intent had gone into making the system. Maybe he was just bad at
practicing what he preached, but he started writing code comments after that.

And that’s someone unable to get into their own mindset, it’s much, much worse
if the code is handed off to someone else. If I task two developers with
solving the same problem, as clear as they possible can using self-explaining
code. Well, I’ll get two very different results, because what clear code is,
is very subjective.

------
Chazprime
Respectfully, I think this article contains some really terrible advice. Based
on his examples, I think his chief complaint should really be that programmers
should stop writing _unnecessary_ comments, which I’m actually okay with.

 _If you can’t write expressive code, own up to your failure and write a
comment. You are responsible for the code you write, so never leave poorly
written code unexplained._

While in theory it’s possible that every member of your team could write code
that’s so expressive that it never need comment, in reality you’ll find that
different programmers adhere to different naming/styling conventions and
sometimes being able to see the author’s steps laid out in comments leads
easier corrections to errors in logic or better refining of the process
itself. Good code commenting practice means that new team members can more
quickly adapt to the codebase, or even programmers who are coming back to
their older work after some time or a major life event. Invariably there will
be times where programmers naturally go through cycles of sprint/crunch and
code cleanup, it’s the nature of the work.

------
simonblack
Comments don't tell you 'What', they tell you 'Why'.

