Comments
[This content is no longer valid. For the latest information on "M", "Quadrant", SQL Server Modeling Services, and the Repository, see the Model Citizen blog.]
The following guidelines provide recommendations for adding comments to Microsoft code name “M” source files.
Consider Using Comments to Document Complex or Ambiguous Code
Consider documenting code that would not be intuitively understood by a professional developer. For example, consider documenting each clause in a complex constraint or the purpose of a field if it is not self-evident from its name.
Avoid Using Comments that Repeat Self-evident Information in the Code
Avoid using overly simplistic comments, such as "Fields" or "Computed Values," which state “M” coding concepts that would be familiar to most developers. Do not simply restate the names of types or fields in comments.
Avoid Using Comments to Leave Unused Code in a Source File
In most situations, you should not use comments to leave unused code in source files. There are occasions when leaving unused code is useful. For example, you might be writing a single feature over multiple check-ins of the source files. These scenarios should be rare and short in duration.
Do Use the “//” Commenting Style for Single and Multi-line Comments
The following “M” code snippet follows this guideline.
// Last date there was any form of contact with the person.
LastContacted : DateTime?;
// Age of the person stored where the date of birth is
// not known reliably.
Age : Integer32 where 0 <= value && value <= 123;
Avoid Using the “/*. . . */” Commenting Style
Use the “//” commenting style in most scenarios. The following “M” code example incorrectly uses the “/*…*/” commenting style.
/* Age of the person stored where the date of birth is
not known reliably. */
Age : Integer32 where 0 <= value && value <= 123;
Do Place Comments on Separate Lines above the Associated Lines of Code
Comments should go on their own line immediately before the line of code that it applies to. Do not include comments on the same line as code or inline with code. The following “M” code example incorrectly places the comment after the line of code rather than on a separate line above it.
Age : Integer32 where 0 <= value && value <= 123; // If date of birth unknown
Do Not Use a Blank Line between a Comment and the Declaration to which it Applies
The following “M” code example follows this guideline.
// Last date on which there was any form of contact.
LastContacted : DateTime?;
The following “M” code example contains two incorrect examples. The first example incorrectly includes a space between the comment and the associated code line. The second example incorrectly adds a blank comment line between the comment and the associated code line.
// Last date on which there was any form of contact.
LastContacted : DateTime?;
// Last date on which there was any form of contact.
//
LastContacted : DateTime?;
Do Use a Blank Line after a Comment if it does Not Apply solely to the Declaration that Follows
In most situations, you would not use a blank line between comments and code. However, if the comment does not apply only to the line of code that follows, it is acceptable to separate the comment and the following code line with a blank line.
Do Use #if Blocks to Temporarily Isolate Code that is Impacted by Entries in a Bug Tracking System
Use the bug tracking system’s identifier in the label so that affected code can be found easily when bugs are resolved or postponed.
// UI temporarily requires age be optional and unconstrained.
#if 12345
Age : Integer32 where 0 <= value && value <= 123;
#else
Age : Integer32?;
#endif