Henooh Commenting Guidelines
Commenting code is an important part of programming. Being a good software engineer requires not only producing
working and efficient code, but also making his work understandable to others or his team in the future.
Make sure to use XML documentation, since this is immediately picked up by Visual Studio and used by
intellisense. The XML documentation is also picked up by Henooh Document Generator to produce online
Commenting in Henooh Framework is important. The way Henooh Framework is setup, comments in the code will
generate related documentation. With combination of XML comments, Henooh Document Generator used
in Henooh Framework generates online and offline documentation.
General Commenting Conventions set by .NET Framework.
- Place the comment on a separate line, not at the end of a line of code.
- Begin comment text with an Uppercase letter.
- End comment text with a period.
- Insert one space between the comment delimiter (//) and the comment text.
- Do not create formatted blocks of astrisks around comments.
Henooh Framework Commenting Guidelines.
- Multi-line block comments are strongly discouraged. Do not use multi-line comments for commenting.
- Use Ctrl-K, Ctrl-C to comment multiple lines, and Ctrl-K, Ctrl-U to undo comment on multiple lines of code.
- All files, (container for classes, interfaces) will have a header comment.
- Header comment is composed of , and tags. tag is optional.
- Summary tag is a couple line sentences that describes overall functionality of the class.
- Remarks tag contain technical details and description of the class.
- Use only approved tags for comments.
- Follow Version Control Guidelines to modify revisionhistory comments.
If you are editing any code, you are required to add an entry to revision history with planned SA version.
You should add date, solution archive version, current project version and description of changes.
Using Henooh Document Generator.
- For Libraries, Overall library comments belong under Namespace of the library. Create _NamespaceDoc.cs file
for library comments.
- For Applications and Apps, comments belong under App.xaml.cs file.
- Consider all comments in the summary and remarks tab to be properly formatted paragraph.