My rules for good docs: 1. Begin with a usage synopsis in the form of sample code. It should hit the most important functions and show how they fit together. E

My rules for good docs: 1. Begin with a usage synopsis in the form of sample code. It should hit the most important functions and show how they fit together. E.g. for a drawing library, show how to instantiate an image, draw a circle with arbitrary fill and stroke colors, and write the image to disk. 2. For each function or method, open your comment with a straightforward description of what the function does, even if it's absolutely, undeniably obvious. If you're writing an math library, you should even say what the sqrt function does. It doesn't hurt, it costs you very little effort, and you might help someone who's just beginning to learn about the problem domain. 3. For each parameter, document its possible types if your language doesn't encode that information in the function signature. Even if you're using something like Haskell where it does, you might need to comment on the type. E.g. if sin takes a float, say whether it's in degrees or radians. 4. Provide sample code for functions that have to be used in tricky ways. E.g. if the function requires special setup or context.