The [[http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide][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 ;) -- Main.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.