Code Comments And When To Use Them

tl;dr: Don't. Basically any information you might want to put in a code comment is better communicated somewhere else.

I maintain that there are actually very few legitimate reasons to add comments to code (I thought of one). On the other hand, I can think of a number of reasons one might be tempted to comment code, so below I will address every reason I can come up with.

Who? When?

It should be obvious that who edits a given file (and when they edit did) should be tracked in a version control system. However at work we use an IDE (PHPStorm) which inserts this information at the top of each PHP file it generates, and most people don't bother to remove it.

(PHPStorm also inserts the fact that it was the tool the developer used to create this particular file. As far as I'm concerned this is nothing but a not-so-subtle advertisement, even though PHPStorm is a paid product. Gross.)

How?

As in "How does this code work?", often intermingled with the code itself. I know this gets harped on by many others, but code will be read much more than it will be written. Please consider rewriting the code if you think a comment would help improve readability. These comments might be the worst, because, like chocolate covered olives, they are little time bombs of lies and deceit. On the surface they seem wonderful, but in time the implementation will change. When it does you are left with a olive-flavored bug because the next person read the comment and believed it.

Just don't.

Why?

Version control comes to the rescue again! Each commit should be accompanied by a clear commit message, which finishes this sentence: "If/when this commit is applied, it will ....". Arvid Andersson has an excellent guide for commit messages. Please read it.

"We'll need this code again soon...."

No, you won't. I've seen commented code that was several years old. I've also seen code that was commented inside a larger block of commented code. Please stop. What's the point of using version control if not to maintain a history of edits? (I know version control has other uses; don't @ me.) If you aren't using version control, and you started coding more that a few months ago, either start using it, or find something else to do with your life. You're only hurting yourself.

TODO, FIXME

Issues belong in an issue tracker. BitBucket, GitHub and GitLab all offer issue tracking, even with their free plans. You're likely using one of these services anyway. Even if you aren't using one of these services, Trello is free, and it is still a better issue tracker than code comments. Honestly a shared spreadsheet on Google Docs would be better than code comments.

I'm sure there are other reasons developers use code comments. (Laziness?) Some might even be legitimate. (Laziness is not!) Below are the reasons I believe a developer might genuinely need comments.

Types

Several popular programming languages allow developers to play fast and loose with types. Since doing so can easily lead to bugs, different communities have adopted standards for declaring expected types in specially-formatted code comments, which may be check by separate tools. In general I recommend using these minimally and only as a last resort. If the language provides a way to declare types natively (PHP type hints), prefer the native solution and leave comments for edge cases. These comments can be useful, and there's really not a better place to put the information. However if the type comments are not checked often and on a regular basis, they will tend to become lies.