COMP2100
Eiffel Coding Standard

This coding standard is based on the discussion in Chapter 26 of Object-Oriented Software Construction (2nd edition) by Bertrand Meyer.

1. Class and feature names

1. Use full words, not abbreviations: e.g. number not num.

2. Connect the words in multi-word names with underscores: e.g. entity_name.

3. Do not include the class name in the name of a feature: e.g. in class PART, use number not part_number.

4. It's OK to use the name of the class as the name of the only feature of that class: e.g. text_formatter: TEXT_FORMATTER.

It's OK to use single-letter names and abbreviations for locals and routine arguments.

2. Upper and lower case

1. Class names in all upper-case: XML_DATA_ELEMENT.

2. Constant attributes and once functions with a leading capital letter: Pi: DOUBLE is 3.14159.

3. Feature names, locals, routine arguments in all lower case.

4. Keywords (words that are part of the Eiffel language itself, like "feature", "do", "end" etc) should be in all lower case except for Current, Result, Precursor and the predefined boolean constants True and False.

3. Grammatical category

1. Class names should always be nouns, possibly qualified: XML_ELEMENT, XML_CONTAINER_ELEMENT. Deferred classes describing a property can have an adjective name: COMPARABLE, HASHABLE.

2. Names of commands (procedures) should be verbs in the imperative ("Do this!"), possibly with a direct object: make, visit_paragraph.

3. Names of queries (attributes and functions) should be nouns, possibly qualified: value not get_value. The only exception is for booleans, whose names should be adjectives: known, finished. Because a feature called empty could mean "Is this empty?" or "Empty this!", it's better to remove any ambiguity by calling it is_empty.

4. Constants

1. In general avoid the use of manifest constants (like 17 or "fred") except for 0 and 1, and strings that are only used once.

5. Header comments

1. Every class must have a header comment explaining what objects of this class do, and including author, date and version control information.

2. Every routine must have a header comment.

3. Routine header comments should be clear, informative and as short as possible. Remove everything that isn't necessary.

4. Don't repeat information that's in the require or ensure clause.

5. Don't use phrases like "Return the..." or "Computes the..."

6. Header comments for queries (both functions and attributes) should be a noun phrase describing the thing to be returned. For example in class STACK:

      top: T is
            -- Top element
         require
            not_empty: not is_empty
         

   rather than

      top: T is
            -- Return the top element of the current stack,
            -- which must not be empty when this is called.
         require
            not_empty: not is_empty
         

7. Header comments for boolean queries should always be in the form of a question, ending with a question mark. (If the answer is "Yes", the result will be True.)

8. Header comments for commands should read like a command: they should be phrased in the imperative voice like an order.

9. Group features with similar function into separate feature clauses, each with its own very short header comment, on the same line as the keyword "feature", describing the group: "Initialisation", "Implementation", "Access" etc.

10. References to attributes, arguments etc in header comments should be quoted between a left quote and a right quote: -- Insert `x' at position `i'.

11. Non-header comments within routine bodies should be at a higher level of abstraction than the code itself. Definitely not:

          i := i + 1  -- Increase `i' by 1.
          

6. Layout and indentation

1. Use the indentation provided by the Emacs Eiffel mode.

2. In general each construct should be on a separate line. If you need to use a semicolon except between routine arguments, don't. Use a newline instead.

3. Use Meyer's "comb" structure (see OOSC2, pp. 891-5) in its more expanded form. Here is an example class:

   class
      
      EXAMPLE
      
         -- Objects that don't do anything useful, as an example of
         -- formatting.  (Based on the example in Object-Oriented
         -- Software Construction (Second Edition) by Bertrand
         -- Meyer, page 895.)
      
         -- Ian Barnes, 24 April 2002
      
   inherit
      PARENT
         redefine
   	 f1, f2 
         end
      OTHER_PARENT
         rename
   	 g1 as old_g1,
   	 g2 as old_g2
         redefine
   	 g1
         end
      
   creation
      make
      
   feature {NONE} -- Initialisation
      
      make is
   	 -- Set things up.
         require
   	 label_for_stack_dump: correct (x)
         local
   	 x: TYPE
         do
   	 if a then
   	    do_something
   	 else
   	    do_something_else
   	 end
   
            -- A simple loop can have lots on one line...
   	 from i := a.lower until i > a.upper loop
   	    do_something
   	    i := i + 1
   	 end
         
   	 -- ... but a complex one is better spread out.
   	 from
   	    complicated_initialisation
   	 until
   	    complicated_exit_condition
   	 loop
   	    do_stuff
   	 end
         end
      
   feature {ANY} -- Access
      
      my_attribute: SOME_TYPE
   	 -- Explanation of its role.
      
   invariant
      some_condition
      
   end -- class EXAMPLE
         

7. Spaces

1. Use a space before a left parenthesis, but not after: f (x) not f(x) or f( x ).

2. Use a space after a right parenthesis unless the next character is punctuation like a comma, but not before: f (x) + 1.

3. Use a space after a comma but not before.

4. Use a space after the two dashes that start a comment.

5. Use a space after the colon in a declaration but not before: i: INTEGER.

6. Use a space before and after all arithmetic operators: a + b.

7. Don't put spaces before or after the dot in a feature call.