Go to the source.

The code tells the true story.

Since only the source tells us what the code is truly doing, you want to make it as readable as possible. There many things one can do to improve the quality of the source code for the reader. Future programmers will be thanking you.

Comments and design documents will go out of date. Sometimes they’re outdated before the primary development is even finished. Thus it is best if the comments not describe what the source is doing. Instead, comments should explain why the objects and methods exist. The reader would love to understand why some decisions were made.

Another thing to do is to use meaningful names. Avoid technical jargon. Instead, use words from the business domain. If the code itself can tell the story, then there is less need for documentation that is rapidly going out of date. It also helps if you refactor to smaller methods. When a method has only one job, its name tends to be more accurately descriptive.

One more thing that will help future readers immensely is to have excellent test coverage. A well-written test explains the intended behavior. Some tests also contain examples that can describe how the application should handle edge cases, situations that might not be covered by other documentation. Great tests are the best!