All files should have a block comment at the beginning of the file that provides the following information:
Specific file types may have additional requirements for this block comment. Specific details can be found in the language-specific notes for a given language.
Internally, code should be made as self-documenting as possible by using meaningful variable names, function names, and class names. However, it is helpful to have comments describing complex sections of code and any other parts of the program that would be more readily understood with additional information. Comments should also be included at the beginning of each function. This comment block should describe the function’s purpose, the function’s parameters, the function’s return value, and any other relevant information.
When an application can be optimized or has tasks outstanding, it may also prove helpful to include a simple “TODO” comment, such as the following:
//TODO: One line explanation of the task to be done.
This allows for someone to grep all files for the string ”//TODO: .*” and to easily produce a list of outstanding tasks.
In addition to internal comments, all web-based applications should include a non-technical README, outlining the basic purpose and functionality of the application, and a technical README outlining the basic interaction of the files and any pertinent technical details that would be beneficial to a developer working with the code for the first time. The technical README should also contain the following information: