XDoc Style Guide

The style guide for writing Javadoc comments is a useful starting point for a style guide for writing xDoc comments for Stratego.

[this guide should be rewritten to Stratego context ;) -- MartinBravenboer - 04 Aug 2003]

• Okay to use phrases instead of complete sentences, in the interests of brevity. This holds especially in the initial summary and in @param tag descriptions.
• Use 3rd person (descriptive) not 2nd person (prescriptive). The description is in 3rd person declarative rather than 2nd person imperative.
  • preferred: Gets the label.
  • avoid: Get the label.
• Strategy descriptions begin with a verb phrase. A strategy implements an operation, so it usually starts with a verb phrase:
  • preferred: Gets the label of this button.
  • avoid: This method gets the label of this button.
• Class/interface/field descriptions can omit the subject and simply state the object. These API often describe things rather than actions or behaviors:
  • preferred: A button label.
  • avoid: This field is a button label.
• Add description beyond the strategy or module name. The best names are "self-documenting", meaning they tell you basically what the module/strategy does. If the doc comment merely repeats the name in sentence form, it is not providing more information.