Comments in Code Snippets
Developers add code comments to code snippets and demos to clarify the logic behind the code lines and to help users better understand the implementations.
In This Article
General
- Throughout the years, developers cultivate individual approaches to writing comments in code snippets and demos.
- Code comments are used within the code blocks and not in the help topics content. However, the individual developer approaches lead to inconsistencies and affect the quality of the documentation.
- Comments inside code snippets are not a common topic for documentation style guides. However, to ensure consistency, this article lists some general recommendations.
Guidelines
- Write comments in (American) English.
- In JavaScript, use single-line comments. In other programming languages, use block comments.
- Try to keep a comment line up to 80 symbols long. Comment lines longer than the viewport need to be scrolled by the user to be seen.
- Whenever possible, try to deliver the comments as full sentences.
- When the comment consists of full sentences, start each sentence with a capital letter and end it with a period.
- When the comment is fragmented, start it with a small letter and end it without a punctuation mark.