Comments… I know right… What a 🔥 topic to discuss. I hope the servers can handle our excitement…
But jokes aside. If you work daily with code good comments are essential to your productivity in any mid to large sized codebase. Ugh. What a buzzkill…
So let's get to business: Comments aren't additional to a good codebase. They are the codebase.
Here a few tips to enable you to write better comments…
"Comments shouldnt be needed. Good code should explain itself what it does."
If you assume this you misunderstood what comments should do.
Comments should never explain what the code does. The code itself should.
Comments should explain why it exists, and why it exists in this way
class Newsletter # removes stuff from newsletter def remove(stuff) … end end
class Newsletter # Note(andreasklinger): In case we run into XYZ we need to remove the user to avoid # problems w/ ABC and DEFG's API. Read more here: https://..... def remove(stuff) … end end
At Product Hunt we have the habit of always leaving a name next to a comment.
Note(andreasklinger): This is a comment.
But you can use git blame for that.
People will move code around, People will edit your lines (remove trailing spaces anyone?).
Nobody will bother to find the author once code got moved around or edited often enough.
Especially in smaller teams just the name alone helps you to understand why something exists or if you should bother trying to fix/improve it.
The "next developer taking over" is almost a myth.
Usually the "next developer" is just "quickly passing by" has her own thing she wants to get done and your code got in the way.
Imagine the next person landing in your code to have no context whatsoever and VERY limited time to change it.
While you wrote the code it was obvious to you - it will never be that obvious again - to no-one, including you.
Explicit > Implicit BUT you want to avoid explicit when explicit becomes redundant.
Write your comments.
When you wrote your comment read it again and see what you can remove or simplify.
If you can't explain it simply, you don't understand it well enough.
- Albert Einstein
Comments aren't additional to a good codebase. They are the codebase.
While code makes a complex systems manageable for machines comments make them manageable for humans.
feel free to hit me up on twitter!