This article is Part 5 of 11 in a series about Habit of a Solid Developer.
- Part 1 - Introduction
- Part 2 - Automatically Enforce Project Conventions
- Part 3 - Self Prescribed Code Reviews
- Part 4 - Git Dance
- Part 5 - (current) - Update or Add Documentation while Reading Code
- Part 6 - Dig a Little Deeper
- Part 7 - Changes Should be Taken with Baby Steps
- Part 8 - Podcasts
- Part 9 - Rapid Feedback
While I generally sit on the side of the fence that your code should read clearly enough that comments should not be necessary. I concede that there are (often) times when a comment can really help to make the job of understanding the code much easier than just how a variable or method is named or organized.
One example of such case is when you've gotten lost in the code and don't understand how a piece of it works.
The second you figure or re-discover it's intent, try to add or update some comments in the code that may help you or the next person understand it more clearly in the future.
You can argue that a comment should have been added initially, but life happens and we don't always save little nuances like we should or we're given a codebase that is not as clean as we would like. So if you catch yourself digging through some code and a bit confused in an area, take the time to document it (once you figure out what you didn't understand).
This is especially true when you are the original writer of sed un-clear code. I know I've gone through code I've written and been like, "hmm, no idea what I was thinking here..." or "well, there was a reason I did this stupid thing, but now I don't remember what that was. Wish I would have commented a little more to my future self".
Sometimes it may be a simple variable rename or refactor that would clean it up. But don't just figure it out and not leave a breadcrumb for the next person (or yourself) to more easily grok the code.
Add clarity to un-clear code.
// When I wrote this, only God and I understood what I was doing // Now, God only knows // // http://stackoverflow.com/a/316233/1402137
Now go read these comments and enjoy!