Documentation
Commenting
It is a really good idea to write comments explaining your design and purpose. This allows you and anybody other using your code to understand what it is doing, how to use it and how it has been designed and implemented.
It is a good idea to abide by the following conventions:
Above the class definition, explain in 1-2 sentences what this class represents. Be specific: a reader should be clear about what one object of this class represents. This explanation should include both semantic details (e.g. what the class represents from the problem statement) and technical details (e.g. useful for a fellow designer/programmer). Also mention any details that a user of this class may need to know to use it appropriately.
Before each method (including the constructor and getters) write the purpose statement for the method. Also include a list of any arguments along with what they represent, and what the method returns. If the method throws exceptions in certain situations, the comments should enumerate all such possibilities along with what kinds of exceptions are thrown.
The purpose statement answers the question “what does this method offer?” in the first sentence. The statement should not merely be an English translation of the method signature, but should be in plain, non-technical language. If this method changes the calling object, the changes should be explicitly stated. If appropriate, include examples of how to call the method, and what that call will achieve.
Within the method body mention any details that you think are relevant to what that method is doing.
A good rule of thumb is to assume that the audience for your comments is not you, but other designers/programmers who will use your code. If the language is such that only you can understand it fully (because you implemented it) revise the comments.
Formatting
Documentation is critical to making code understandable, readable and usable. As programmers we are both producers and consumers of documentation. Any good code base comes with copious and helpful documentation. For example “official” Java documentation is available online. You can read about the String class that we used above here.
Java comes with an in-built tool that helps you generate such html web pages from documentation written in your Java code. This tool is called Javadoc. This tool “reads” your comments and converts them into html. You can use specific formatting commands within your comments to facilitate generating pleasing documentation. In addition to the Javadoc-specific annotations (like @param, @return, etc.) Javadoc can handle any HTML syntax. This means you have the power of HTML at your disposal to format your documentation suitably.