It's time to get a bit controversial. I don't think you should
write comments in your code pretty much most of the time. Here, we have some code
where we expect the value to be 5 Looking at this code, it's not obvious
what five signals. We could add a comment
explaining what five is, but even better we can create a constant
representing the variable instead. The if statement now reads like a comment: that we want status to be message sent. If your code is complex enough that it
warrants a comment, you should instead see if you can simplify or refactor
the code to make it better instead. Right now,
this condition is complex enough that we add a comment explaining it,
but we can simplify this by using variables
to name parts of the expression. Now the
condition reads like the comment does. So the comment is basically redundant
and can be removed. When conditions are complex
enough like this, you could also consider moving
the whole condition to its own function. Now you don't need to decipher at all. Types can also make comments redundant. In C++,
there's no built in memory management. You often have a function like this
where you get back a thing, but we need to make clear
who will take ownership of the thing. Ownership, meaning the responsibility to release the memory
after everyone is done with it. In older C++, you pretty much
had to rely on comments to do this. If you were given ownership of an object,
you'd find out by reading the comments of the function. But C++
added a new type called unique_ptr. The type represents
a unique reference to the object. So if you get one, congratulations! It's now your responsibility. The type tells you explicitly that you now own it
without the need for a comment. And even better, the type makes it
so you get a compile error if you do bad things with it. A comment doesn't do that. Likewise,
if we have a function that returns an int, but that int is optional. We could add a comment
saying that -1 means we're not actually returning a value. But even better, we could use a type. If we return an optional int instead, it's now obvious
that we might not give a value. We can't miss the comment
and not realize that we might get an invalid timestamp back. The user needs to handle a missing value
or they'll get a compiler error. You might wonder why don't we just make our code
high quality and add comments anyways? Isn't more comments just better? That ignores the problems with comments. Comments get bugs like code. When people make changes to code, they often don't
update the comments to match. But unlike comments, we have tools to stop
bugs from entering code. We have tests, compiler
checks and limiting. We don't have any system like that
for comments. Maybe one day we can have some static
analysis tool that uses AI to determine if the code matches the comments and flags
any discrepancies - there's a start up idea - but
because of this I don't trust the comments even when they exist. Comments can lie, but code cannot. So when trying to understand what
a piece of code does, I read the code. I never read the comments. Maybe it's just me. Do you guys find yourself
reading comments to understand code? What I do read is code documentation. Code documentation describes
the high level architecture and public APIs of a system. Code documentation differs from comments where comments describe the internals
of how your code works. Documentation describes
how you use the code. The world needs more high quality
documentation, and while we could write the documentation
for our code completely separated from our code,
it makes sense to keep our documentation as close to the code as possible
in order to try to help them stay in sync. Tools like Doxygen, pydoc and JavaDoc
generate documents directly from code files
and therefore change alongside our code. It's useful to document
what a class or API represents and any expectations
for interface definitions like thread safety,
possible states or error conditions. This helps the consumers of the API
know how to use it and also helps any new implementers of the interface know how they're supposed to operate
and behave. The guidance I've given about comments
still applies for documentation. If we write better APIs,
our documentation will be more concise and less prone to errors. But I concede that you'll never be able
to make all of the parts of the system obvious with pure code. I do think there's a few cases
where you should consider comments: if the code does something non-obvious
for performance reasons, a comment can help explain
why the code looks weird. If the code is utilizing a specific mathematical principle
or an algorithm from a particular source you might consider linking to the source
to help future maintainers. There's this comic called comic strip, and one of the comics is about a guy telling a developer that one day
we won't need code in the future because you'll be able to simply write a spec
and the program will just write itself. The developers are casting retorts
that code is just a more precise way of writing a spec. I mean, I think it's wrong. And A.I. is coming for all our jobs,
and we should be afraid of the impending sociopolitical turmoil
that comes when our best tool for distributing wealth,
the job disappears. But alas, it still helps my point. Code is a much better way to express
intent than comments about code. So in general, if you feel like you need
human language to describe your code, see if you could make your code
more human. What other cases
do you think comments are needed?
