Documentation Comments

Comments in your code are very important for maintainability and helping other people understand your code. Documentation comments are especially effective at describing the purpose of protocols, structures, methods, data types, and other elements of program code.

Documentation comments should be applied consistently to all public APIs since they are a valuable asset for SDK consumers.

Tips for writing effective documentation comments:

• Write in plain U.S. English.
• Write complete sentences and paragraphs.
• Write clear and brief comments, no more than a few sentences.
• Follow the approved style guide for your programming language.
• Avoid creating running words that are not compound words. For example “notready” is two words run together. Use an appropriate separator, for example “not ready”, “notReady”, “not_ready”, or “not-ready”).
• Always add value. Don't restate what is already indicated by the type signature.
• Describe units of measure and integrity constraints of variables.
• Link to conceptual documentation for more complete descriptions of how APIs fit together as a whole.
• Follow the approved style guide for your programming language. See the Development Readme for style guidelines related to specific programming languages.

What documentation style guidelines should I follow?

It is important to try to follow documentation style guidelines to ensure that the documentation, even comments, can flow together. See Documentation Style Guide.

Also, see the Development Readme for style guidelines related to specific programming languages.