Naming Conventions PreviousNext

All names appearing in the software, comments, directory names, documentations, etc. should be written in American English.

Class Names

In order to avoid class name clashes between different libraries, some Eiffel compilers support class renaming in the ECF file or equivalent. But some don't. Therefore the name of the classes should systematically be prefixed with a two-letter library code followed by an underscore. For example the classes from the Gobo Eiffel Structure Library have been prefixed by DS (which stands for Data Structures), as in DS_CONTAINER, whereas classes from the Gobo Eiffel Lexical Library have been prefixed by LX, as in LX_SCANNER. Some libraries may use several prefixes, provided that they are not already used by other libraries. The list of already used prefixes per library will be available on-line.

Class names should usually be singular nouns, such as DS_STACK. If the noun is qualified, words should be separated by underscores, as in DS_LINKED_LIST. Class names in Eiffel are written in upper-case letters and it is considered bad style to use letter-case difference to concatenate words such as LinkedList for example. The name of deferred classes can also be adjective when they describe a property, such as DS_SORTABLE. It is suspicious to have verbs as class names since classes should describe objects rather than actions.

Classes containing only constants can have the suffix _CONSTANTS and those containing only facility routines can have the suffix _ROUTINES. Some classes are used as a means to share objects using once functions. These classes can have the word SHARED just after the prefix of the class. For example the class used to share a singleton object of type KL_ARGUMENTS is called KL_SHARED_ARGUMENTS. An alternative is to use IMPORTED instead of SHARED when the purpose of the class is not to give access to an object but rather to routines or constants without the inconvenience of polluting the feature name space with mixin classes. Have a look at KL_IMPORTED_STRING_ROUTINES as an example.

In Eiffel it is considered bad practice to use abbreviations in class and feature names. However this can be accepted when the abbreviation is commonly used in the domain of expertise such as LX_DFA for example, which stands for Deterministic Finite state Automaton and is used for compiling regular expressions.

Filenames

Some the Eiffel compilers supported in the Gobo package do not allow to have several classes in the same file (even though some might). So each file should contain only one class.

Likewise, some Eiffel compilers expect by default to have a one-to-one relation between the name of the class and the name of the enclosing file. Therefore the name of the file should be the name of the class followed by the extension .e, all in lower case. For example file ds_list.e contains class DS_LIST.

Cluster Names

Library classes should be organized in clusters in $GOBO/library/<library-name>/src. Likewise the source code of tools should be put in $GOBO/tool/<tool-name>/src.

Cluster names should be in lower-case and words should be separated by underscores. Abbreviations should be avoided unless well accepted and understood in the domain of expertise of the underlying library. Exception to this rule is spec for Eiffel compiler dependent clusters. For the cluster spec, compiler-dependent classes should have the same name and put into the two following clusters:

spec/ise -- Implementation for ISE Eiffel
spec/ge -- Implementation for Gobo Eiffel

Only one of these clusters will be included in the ECF file or Xace file of the application depending on the Eiffel compiler used. These clusters can be automatically generated with the tool gepp if the different implementations are put in a single file whose extension is .ge instead of the Eiffel extension .e. I usually find it easier for development and maintenance to have these .ge files.

Feature Names

Feature names should be in lower-case and words should be separated by underscores. Abbreviations should be avoided unless well accepted and understood in the domain of expertise of the class. Names of constants can possibly have upper-case letters, but in that case please make sure that all calls to this constant use the same letter-case in order to be compilable by case-sensitive Eiffel compilers. Note that, even though none of the currently supported Eiffel compilers is case-sensitive, the previously supported compiler SmartEiffel was case-sensitive (when not using the -no_case_sensitive command-line option).

Names of procedures should be verbs as they describe actions or commands. On the other hand names of functions or attributes should be nouns, possibly qualified, as they describe entities. The names of boolean queries should have an interrogative form as in is_empty, is_closed or has_error. They can also be simple adjectives such as closable, or past participles as in found.

Names of creation procedures usually start with make in Eiffel, for example make or make_from_string.

Names of factory functions can have the prefix new_*, as in the following example:

_   new_foo (a_string: STRING): FOO
_   _   _   -- Foo made up of characters of `a_string'
_   _   _   -- (Create a new objet at each call.)
_   _   require
_   _   _   a_string_not_void: a_string /= Void
_   _   do
_   _   _   create Result.make_from_string (a_string)
_   _   ensure
_   _   _   new_foo_not_void: Result /= Void
_   _   end

Feature Category names

All feature clauses should be equipped with a comment, as in the following example:

feature -- Access
feature {NONE} -- Initialization

Here are some examples of feature category names, taken from the Gobo Eiffel Structure Library documentation:

-- Initialization
Creation procedures.
-- Access
Queries used to get elements or properties about the container.
-- Measurement
Queries concerning the number of elements and size of the container.
-- Status report
Queries used to determine general boolean properties of the container.
-- Comparison
Equality tests between containers.
-- Duplication
Features which produce copies of the container.
-- Setting
Procedures which change the general properties of the container.
-- Cursor movement
Procedures that change the cursor position.
-- Element change
Commands which add or change items in the container.
-- Removal
Commands which remove items from the container.
-- Resizing
Commands which change the size of the container.
-- Implementation
Secret features used for implementation purposes.


Copyright 2001-2016, Eric Bezault
mailto:ericb@gobosoft.com
http://www.gobosoft.com
Last Updated: 22 December 2016
HomeTocPreviousNext