Class names

In order to avoid classname clashes between different libraries, some Eiffel compilers support class renaming in the Ace file or equivalent. But some don't. Since it is a priority for the library to be portable across all Eiffel compilers available on the market today, the name of the classes of the Gobo Eiffel Structure Library have been systematically prefixed with the two-letter library-code DS, which stands for Data Structures. For example the class name for lists implemented with linkable cells will be DS_LINKED_LIST.

Apart from this library-code prefix, class names generally follow the same convention as those adopted in EiffelBase, with some exceptions mainly for consistency reasons. Names of classes which describe an abstract property are typically adjectives, such as DS_TRAVERSABLE or DS_RESIZABLE. More concrete, but still deferred, classes are DS_LIST, DS_STACK or DS_TABLE for instance. And finally these data structures are given various implementations in descendant classes. There are five main kinds of implementations. Data structures implemented with singly linkable cells have their names prefixed by LINKED such as DS_LINKED_LIST or DS_LINKED_STACK. Other containers like DS_BILINKED_LIST are made up of doubly linkable cells. A third alternative is to use an array internally, as in DS_ARRAYED_LIST or DS_ARRAYED_STACK. To avoid too many resizing of these internal arrays, some containers are implemented with a list of array chunks, such as DS_MULTIARRAYED_STACK. And finally data structures using a hashing mechanism will have their class names prefixed by HASH, DS_HASH_TABLE being an example of such class naming.

Feature names

The Gobo Eiffel Structure Library follows the conventions specified in Dr Meyer's book: Reusable Software, the base object-oriented component libraries. Apart from the Eiffel style guidelines, which are enforced in all Gobo Eiffel libraries, this book also describes the principle of naming consistency and explains why it is so important when writing resuable libraries. Since I won't be able to explain it better than Bertrand Meyer, I'll let you read section 3.8 of his book, Naming Issues, for a detailed description. If unfortunately you don't own a copy of this book, you can still read the article Rules of Component Builders published in Software Development online magazine and from which the following paragraphs are extracted:

One lesson my colleagues and I learned early in the development of Eiffel libraries is that some issues viewed as cosmetic in non-component application development take on a critical role in component development. Naming is one of them. [...] The consistency principles imply that the names must not only be clear but also uniform.

In the first iteration of EiffelBase, class STACK had operations push (x), pop, top for an element x; class ARRAY had enter (x, i), and entry (i) for an integer i; class HASH_TABLE had add (x, k), and value (k) for a key k. Using such well-accepted names, each well-adapted to each kind of structure, emphasized specificity rather than generality. This practice is not a problem with a few library classes, but with hundreds of components it doesn't work with the “ease of learning” requirement: it amounts to requiring the library user to learn a specific programming language for every new kind of structure. In each case the effort isn't much, but compounded over the practice of large-scale component reuse it can defeat the best intentions. As a result of these observations, we went to a set of completely systematic naming conventions, which I detailed in Reusable Software:

• The basic replacement or addition operation is always called put (replacing push, enter, add, and so on).
• The basic access operation is always called item.
• The basic removal operation is always called remove or prune.

Of course this may look unusual for programmers used to push, pop and the like, but this principle has been well accepted by the Eiffel community. This is mainly because it is much more important when considering a class library as a whole to emphasize the commonalities rather than the differences. The Gobo Eiffel Structure Library follows the principle of naming consistency and the standardized feature names used throughout the library classes are described in the table below:

after, *_after

Indicate that all items have been visited when traversing a container forward.

append, append_*

Add several items to the container. This is the same as extend except that the container is automatically resized when there is not enough room left.

back, *_back

Move the cursor backward.

before, *_before

Indicate that all items have been visited when traversing a container backward.

capacity

Maximum number of items that the container can hold.

count

Number of items in the container.

delete

Remove all occurrences of an item from the container.

extend, extend_*

Add several items to the container. Contrary to append, extend has a precondition (extendible) which checks whether there is enough room left in the container.

extendible

Indicate whether there is enough room left in the container to add a given number of items.

finish

Move the cursor to the last item in the container.

first, *_first

First item in the container, or operations which will change this first item.

force, force_*

Add an item to the container. This is the same as put except that the container is automatically resized when there is not enough room left.

forth, *_forth

Move the cursor forward.

has

Indicate whether an item is included in the container.

is_empty

Indicate whether the data structure contains at least one item.

is_full

Indicate whether the maximum number of items limit (capacity) has been reached.

item, item_for_iteration

Access an item in the container.

keep, keep_*

Keep several successive items in the container, and remove all the others.

key, key_for_iteration

Access a key in the container.

last, *_last

Last item in the container, or operations which will change this last item.

*_left

Operation to be performed to the left of cursor position.

occurrences

Number of times an item appears in the container.

prune, prune_*

Remove several successive items from the container.

put, put_*

Add an item to the container, provided that it is not full (see is_full).

remove, remove_*

Remove an item from the container.

replace

Replace an item by another one in the container. The number of items in the container (count) is not affected by this operation.

resize

Resize the container so that it will have a new capacity. count is not affected by this operation.

*_right

Operation to be performed to the right of cursor position.

start

Move the cursor to the first item in the container.

wipe_out

Remove all items from the container.

Some feature names will be a combination of two of these standardized names containing an asterisk, such as put_right or remove_first. Their meaning should be straightforward: the first routine will add an item to the right of the cursor position, and the second will remove the first item of the container.

Feature categories

To facilitate class learning, the numerous features of the Gobo Eiffel Structure Library have been organized into categories. The Eiffel language is very helpful here with its Feature_clause construct. Once again consistency is very important. The standardized feature categories used throughout the library classes are described in the table below:

-- 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.

In order to make the search of features easier throughout the class text and flat-short forms, the feature categories generally appear in the same predictable order in the classes.