Source Code Documentation
- All interface members must have a one line Summary comment, and Remarks comments when needed.
- All public members should have a Summary comment, and Remark comments when needed.
- The Summary comment should express the members primary responsibility.
- When writing a Summary comment, prefix the comment with an implicit "I", as in (I) "Exchange data between business and presentation layers."
- The Summary comment for a class or interface should reference the issue ticket.
- All public members not implementing an interface member should have a one line Summary comment, and Remark comments as needed.
- Remarks comments should be embedded in paragraph elements, even if one line.
- Remarks comments should be written in the third person (no implicit "I"). Remarks comments can be "chatty" and suggest recommended usuages, and can discuss design ideas behind the class, if desired.
- An blank comment line can be added before the member singature, to make the signature easier to see.