Terminology |

## 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 `D`ata `S`tructures. 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.