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…

#1 Your comments should explain WHY not WHAT

"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

WHY vs WHAT:

• Code should explain WHAT
• Comments should explain WHY this code exists or WHY it has to do something in a non-obvious way.

Bad:

class Newsletter
  # removes stuff from newsletter
  def remove(stuff)
  …
  end
end

Good:

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

#2 Leave your name

At Product Hunt we have the habit of always leaving a name next to a comment.

eg:

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.

#3 Be thorough

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.

• Explain without the assumption that people already know how your system works
• Explain the quirks of external systems that you have to consider
• Explain the quirks of internal systems that you have to consider
• Explain which parts of the system are Legacy
• Explain when (eg legacy) code can be removed (leave a "after X is done" or a date whenever possible)
• Explain the hacks you needed to do and why they work
• Explain the internal interdependencies that arent explicit (eg other systems relying on structure or api)
• Be ok w/ writing a longer paragraph whenever needed
• Never use external documentation if you can avoid. If it's not in the same file people won't update
• Ask to "Leave a BFN" (leave a big f*** note) - expect also your coworkers to leave notes to any code whenever needed

#4 Avoid clutter

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

Hope that helps!

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.

hth,
feel free to hit me up on twitter!

@andreasklinger