Documenting Code

Updated at 2015-12-16 10:56

Comments should explain why the code exists. Why was it made? When should I use this code? When shouldn't I use it?

Don't say what the code does. The code itself should show what it does. Explain why the code was made, the rationale and thoughts you had when you wrote it.

Take your time to write comments. If a comment is easy to write then that code doesn't need a comment.

Use as few comments as possible. It gets messy and gets out of date.

Keep your comments short. One sentence comments are the best. Reduces vertical space that breaks the flow of the code.

Don't explain awkward logic. Refactor the code by renaming and introducing new functions.