Coding Style Guide

Some proposals on how to format and comment code; usual common Eiffel practises are reccomended of course.

• try to choose feature names that would make code read (as much as) the English language.
• boolean queris should be named is_...., i.e. is_empty
• Describe each feature. Do not leave any feature without a description; while it is surely obvious for the feature writer it may not be so manifest to another person. What a command do? Wha't the meaning of a query? Avoid phrasing like "This feature opens a window", write insted "Opens a window"; instead of "This function returns the number of acorns in tree-hole" write "Number of acorns in the tree-hole".
• try to name feature argument prefixing them with generic english preposition (a_, an_, some_); this make core-reading more fluent IMHO. This is a style introduced in Gobo project and I learned to appreciate it working with Andreas in EWG,
• As an exception to previous rules I suggest to avoid commenting for one-liners. Code like is_parameterless: BOOLEAN is do Result:=(parameters_count=0) end is self-explaining at least to me. Adding a description and formatting it with the usual Eiffel style-guide will make it looks like this:

<code>is_parameterless: BOOLEAN is
      -- Is the function without parameters?
   do
      Result:=(parameters_count=0) 
   end</code>

In my humble opinion it does not add any further informations to the reader.

(Cyril) I don't like one-liners; code should always be correctly indented (the pretty-printer will do it anyway). But I agree that a comment that only paraphrases the name of the feature is useless. On the other hand I'd have added a postcondition:

<code>ensure
   definition: parameters_count = 0</code>

• feature and creation clauses should always have an explicit client list (Liberty will raise a warning otherwise). Of course it may be {ANY}. An empty list i.e. {} means that only the *implicit* Current target (not the explicit Current!) may use it; {NONE} is discouraged and Liberty will raise a warning.

Feel free to make any proposal and improvements.