If I can hand a piece of code off to someone on my team, give them a quick walkthrough, let them at it and not get a call immediately — I’ve commented my code correctly.
I’m in the business of building solutions for other companies and yes, I dislike the documentation part (and yes I dislike the diagramming part just as much, apparently a photo of a whiteboard just doesn’t cut it). As such, I try to minimize the amount of documentation I have to output by leaving it to high-level discussions on code (go to this file) and/or here is where all these configuration files reside.
When I look at code commenting, I generally like to think of it in two parts — Context and Usage.
Context
The Context is the why I have built something the way I have done it. This part is generally to help someone know how to and not to use the code in front of them — i.e., why did I go this route, what were the limitations of the API, why does the order of operations go this way. That sounds like a novel, but generally it ends up being a few lines, referencing other methods. I try to keep my contextual commenting to the classes and methods themselves unless there is something really wonky that I needed to do to make it work, i.e., “DON’T CHANGE THIS SETTING UNLESS YOU WANT TO HAVE A BUSY WEEKEND”.
The Context in your comments is about what you were doing and what you went through while writing this code — and yes it can be humorous as well — not a bad thing. When looking at the context, I do try to avoid referencing ticket numbers as over time, those things die or get migrated or something far worse and then the next developer is left wondering what kernel of wisdom they have lost.
Usage
The Usage is where I look to give some type of indication as to where and how the code should and should not be used. There has been many a time where I’ve received a bug where a fix that was written is now being used in wide-spread environments but was only built for one scenario. If I can help someone that comes after me understand the good or the bad in how to use it, happy to do so (as that helps me understand).
When it comes to usage, I try to keep it as simple as clear as possible — do this, use it this way, it does this — if I find it…
