Comments are added to code to assist the reader in understanding the code. The following guidelines should be observed:
- Comments should not be written to editorialize or entertain. Sarcasm should not be in comments. Questions can be placed in comments, where necessary, to ensure issues are identified and resolved.
- Proper grammar and spelling are required. It reduces the opportunties for misunderstanding.
- Comments, especially in an interpretive environment such as PHP, should be brief. Utilities that strip comments for distribution can eliminate this requirement.
- Careful coding, with meaningful function and variable names may reduce the need for comments. Overly complex statements should be avoided.
- Comments should be considered a visible part of the deliverable product and should be of appropriate quality. If it is a professional product, comments should be professional.
- Comments must be updated to remain current as the code changes.