As you’ve seen so far, documenting code correctly isn’t complicated either, it’s a matter of will and habit of doing so. In short, the basic rules for having well-documented code are:
- Don’t comment on obvious or trivial code.
- Explain anything that isn’t obvious by looking only at the code.
- Always use self-explanatory variable names, even if they are single-use helper variables. They help understanding.
- Use right function names: that explain their role, but are not a paragraph. Simple and concise.
- Describe the least obvious variables, to give them context.
- Explain everything you need, even if they represent several lines of comments. Explaining the business logic inherent to the code helps their management.
- Explain complex concepts that another programmer might not know or remember. It will help you in the future and others if they inherits your code.
- Explain solutions that were tested but ultimately didn’t work. This will prevent others from making the same mistake you’ve already made.
By following these simple basic rules, you’ll get the following:
- You’ll be able to remember how your code worked long after you created it.
- Another will know what your code does and why, without having to decrypt it.
- You’ll be able to know what a complex block of code does without having to analyze a line, just by read it in the comments.
- You’ll be able to find out why a specific feature you’d use today was not used (maybe I had a bug at the time?).
- You’ll be able to rule out other solutions that have been tested before but that gave problems (they may seem obvious at first but had some drawbacks).
Also remember that the documentation outside the code… It’s usually obsolete! The theory is very nice, but I’ve never seen updated documentation. That’s not to say that a project doesn’t have to be documented: the requirements must be there, the tests must be there, but the code is what commands in the end, so…
Spread the CodeDoc movement! For a healthier code!
Would you add anything else?
If you think something I’ve exposed has any bugs or problems, or you think something else might be added, you can contact me on any of the channels shown on the right (or below, if you’re using your mobile). I will be happy to discuss these issues to improve the movement.
Any relevant contributions you make will be shown as yours.