How do I provide good documentation in my code?

Question

I am always wondering what should I write for inline code documentation? I always end up with one liners "This function does x" or a 4 paragraph essay describing every micro detail of the function. I am trying to find a balance that provides good documentation without being to verbose. So if you could replay with the one thing that you find the most helpful when you read inline documentation (ex. describe the inputs, describe what is returned...). Then we will let the community vote up the most important one.

A lot of peoples responses have been centered around writing code that is easy to read/well formed. What makes code easy to read and well formed?

Answer 1

The best-written code should hardly need any comments. If you name your variables and functions well, and write readable and understandable code, the code should document itself. Focus more on writing that kind of code instead of writing hard-to-read code and trying to explain it with lots of comments.

A lot of peoples responses have been centered around writing code that is easy to read/well formed. What makes code easy to read and well formed?

Here are a few that I can think of:

• Variable names that describe exactly what they are for
• Function names that describe exactly what they do
• Don't nest code too deeply
• Use good coding style (indentation, whitespace, etc.)
• Use constants instead of magic numbers
• Don't repeat yourself

Answer 2

well named methods and variable names go a long way in making your code readable. I use comments to document unusual circumstances that need to be taken into consideration.

Answer 3

For a function: Prerequisites that must be satisfied before it can be run. Eg, possible values of arguments, and any ordering info about other functions that need calling first.

Answer 4

Your comments should explain why the code does what it does, not what it does.

Answer 5

Write as little as possible for inline documentation. Focus on writing well factored code that is clear and concise and let the code speak for itself.

Well written unit tests should give excellent documentation for how the code should be used. The code itself should document what it is doing. What is important to document in the code at times is the "why" something was done the way it was done... tricky design decision, needed optimization etc.

Answer 6

Describe what a function/class is responsible for doing/managing/owning, and equally as important, what it is not responsible for.

Answer 7

Describe invariant conditions for a class. Conditions that must remain true from the moment the constructor finishes up to the moment the destructor starts.

Answer 8

Mention any notable exceptions a function may throw.

Answer 9

If you find yourself writing a comment explaining what the next few lines of code do, consider extracting those lines of code out in their own function, and naming the function to explain what the lines of code do.

Answer 10

Read this article about Literate Programming and it might help you.

Answer 11

How and when to comment has been discussed extensively on SO before. You should read through this thread. There are lot of answers there with practical ideas about commenting.

Answer 12

Write comments the way you'd write a highway sign: short, to the point, and helpful for guidance.

Comments are there to guide you to what you're looking for and to warn you of any pitfalls, traps, or dangers ahead. Anyone who's reading your code is going to be zooming by the irrelevant parts as fast as possible, so make sure it's easy for them to see what is and isn't important to them.

If you're writing an API or other public interface, write your comments so that the users of that interface never have to look at the underlying code to figure out what it does.

Answer 13

The best code documentation is to use good Function names, and good Variable/Argument names. That alone should make you code legible at the cost of nothing.

And you can't do better than free ;)