Skillful use of comments

Yesterday, I wrote about how you can anticipate questions a code reviewer might have, and answer those questions as part of your pull request.

When Aaron reviewed my tip, he added a note about also using comments.

I initially interpreted this as comments in the pull request itself. Instead of just writing a long description, you can annotate the changeset with inline comments to give context right when they're reading the specific section of code.

Those comments aren't just for the reviewer to create, you can create them in advance as the author of the code too.

But, that's not actually what Aaron meant. He was referring to comments in the code itself.

And this was an excellent point, so I wanted to share it here as well.

If you feel it necessary to explain the code to the reviewer, it could just be a sign that the code itself needs to be better documented internally.

The PR description (or annotated changeset comments) won't likely ever be looked at again, but the code will.

You don't want to take this too far and start commenting everything in code, but there are definitely cases where an extra comment will help any future developer (even you) when working on that code again.

Here to help,

Joel

P.S. Would you like some help introducing testing to your app? I've helped many teams and developers get started and set up for success.