- The public API is commented. (source)
Generally code comments take one of three forms:
- File-level comments, which provide information about the contents of a file.
- Block-level comments (sometimes known as docblocks), which document the API or usage of a specific function, method or class.
- Line-level comments, which provide inline documention of a function or method's internal operations.
Code can only tell you how the program works; comments can tell you why it works. (source)
File-level comments help provide a sense of the overall structure of the project (the more complex the project, the more helpful they are). Block-level comments provide documentation for the API (for example, they often tell what input is required and what output is expected). Line-level comments can clarify complex code within a function or method, provide contextual references to external resources, and document areas where future improvements may be needed.
Code comments written according to a specification (e.g. JSDoc, phpDocumentor, or one of various Python docstring formats) can be used to automatically generate HTML or other documentation for an application.