- # It should be short and fit on a single line.
- # It should also have meaningful information first in case
- # on truncation by an IDE for instance.
+ # eg. "Error: cannot find method `foo`."
+ #
+ # A good message should:
+ #
+ # * start with a message type like "Error:", "Syntax Error:", "Warning:".
+ # The type is capitalized and terminated by a column.
+ # The rest on the message starts with a lowercase letter and is terminated with a dot.
+ #
+ # * be short and fit on a single line.
+ #
+ # * have meaningful information first.
+ # This helps the reader and remain usable
+ # when truncated, by an IDE for instance.
+ #
+ # * enclose identifiers, keywords and pieces of code with back-quotes.