Comments - Etiquette

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.