Good code is well-documented.

Code must communicate clear sets of instructions not only to the computer but to the poor fools who have to maintain it later.

Supporting documents take time to write and maintain and must be kept up to date with code changes. They can become inaccurate and misleading over time. It can be hard to find the relevant thing you need. Therefore you should not write code that needs to be propped up by external documentation. The code should read clearly on its own.

The only document that describes the code completely and correctly is the code itself. It may be the only documentation available. You should do everything you can to make it good documentation. Self-documenting code is code that is easy to read. Therefore, write your code to be read by humans.

Clear code that does not need comments is best. Avoid comments by writing clear code that does not need comments.

Single Entry, Single Exit (SESE) code is a commonly known idea that a function should have one and only one exit point. This is too restrictive for readable code and leads to deep levels of nesting.

Be wary of optimizing code so that it's no longer a clear expression of a basic algorithm. Only do this if you have proved it is a bottleneck to acceptable program function.

A function should only have one action. Minimize surprising side effects which require extra documentation. Keep the functions short. Avoid magic numbers. Use well-named constants instead. Public information in a class should come first. Hide nonessential information. Do not hide important code. Limit the number of nested conditional statement to avoid hiding important conditions.

Present related information in the same place. Use file headers (a comment block at the top of each source file).

Clear code also contains an appropriate amount of commenting. Only add comments if you can't improve the clarity of the code in any other way.

Donald Knuth conceived an extreme self-documenting code technique called literate programming and he also wrote a book by this name to describe it. The idea is that you do not write a program. Instead, you write a document. The document compiles into the program. Some people were really against this idea and thought it was an unfortunate turn in his career, but there are some good ideas from it to consider. It places emphasis on writing documentation. It makes you think about the code in a different way. You are more likely to update the documentation since it's situated nearby. You will always see the correct version of the code you're working on. It encourages the inclusion of items not normally found in source code comments such as algorithm descriptions, proofs of correctness, and justification for design decisions.

It has drawbacks: it is hard to write. Extra compilation steps are required and good tool support is lacking. You may document code that does not need it and add noise, making missing what is important more likely. Altering the documentation is not possible without changing the source code which can be an issue when you need to update the documentation of already released software.

There are many programming tools that are about halfway between literate programming and external specifications. These are tools which generate documentation from the source code by pulling out specifall formatted comments. This has become popular since Sun introduced Javadoc which generates all of the Java API documentation.

This is an excellent approach to documentation. It is easy to keep documentation up to date. It's natural and does not require much extra effort. However, it is really only useful for API documentation, not internal code documentation.

Remember that you can still write bad documentation with this. Do not document every last detail if it adds no value such as variables with names that it is already obvious what they are. Also document any function pre- or post- conditions, any exceptions that may be thrown, and any of a function's side effects.

The main thing to remember is we code primarily to communicate. The code is the only documentation that will always be there so making it self-documenting. Literate programming is an extreme way to write self-documenting code, and a less extreme way is to use documentation tools that generate API documentation.

Good programmers seek to write clear, self-documenting code with the least amount of extra documentation necessary. They are thinking of the needs of the programmers who will maintain their code.

Bad programmers write unfathomable sphagetti and are proud of it. They avoid writing any documentation and don't care about updating it. They want the code that was hard for them to write to be hard for anyone else to understand.