Difference between revisions of "Local Declaration Guidelines"

Revision as of 12:43, 9 January 2009

Local declaration style guidelines for contributing to the Eiffel Software code repository.

Feature Arguments

Feature arguments should begin with the prefix a_ and nothing more. The prefix a_ represent a contraction of the word argument and does not represent the singular inflection - a noun - Therefore it is not valid to utilize an when the suffixed argument word begins with a vowel. The following is a correct usage:

perform (a_string: STRING; a_integer: STRING): CHARACTER
        -- An example using routine argument variable names.
    do
    end

Here, the second argument a_integer, is not considered A Integer but The Argument Integer, hence the use if a_ instead of _an_.

In-line Agent Feature Arguments

When working with an in-line agent, to prevent conflicts with the enclosing feature's arguments, the prefix ia_ should be used. The same rules regarding English language rules apply here as they do to feature arguments. The IA prefix represents an In-line Argument.

perform (a_string: STRING; a_integer: STRING)
        -- An example using in-line agent argument variable names.
    do
        process (agent (ia_string: STRING; ia_integer: INTEGER)
            do
                ...
            end (a_string, a_integer))
    end

Local Declarations

Routine local declaration should also be prefixed to prevent potential conflicts between routine arguments or class attributes. The prefix l_ is typically used for variable moniker names longer than two character. There are other exceptions, these are discussed below.

Well Known Variable Names

Indexing/counter variables, as used in iteration loops, should not use a local prefix and should be terse. The variable i should be use to indicate it is an index variable. Additional index variables should follow alphabetically from i onwards.

Generally, paired with an indexing/counter variable, a stopping condition count or number-of-items variable is also used. There are two conventions used for this, generally used interchangeably; A count will use the same rules for local declarations and be called l_count, a number-of-items variable will use a well-known contracted variable name 'nb.

perform (a_array: ARRAY [INTEGER])
        -- An example using index and number-of-items local variable names.
    local
        i, nb: INTEGER
    do
        from
            i := a_array.lower
            nb := a_array.upper 
        until
            i > nb
        loop
            ...
            i := i + 1
        end
    end

The case will commonly arise when multiple counters/number-of-items variables need to be used. In such cases the counter/number-of-items variable should be suffixed with the associated indexing/counter variable name. This is akin to [1]'s NEXT x instruction:

perform (a_array: ARRAY [ARRAY [INTEGER]])
        -- An example using multiple index and number-of-items local variable names.
    local
        l_sub_array: ARRAY [INTEGER]
        i, nb_i: INTEGER
        j, nb_j: INTEGER
    do
        from
            i := a_array.lower
            nb_i := a_array.upper 
        until
            i > nb_i
        loop
            l_item := a_array[i]
            if l_item /= Void then
                from
                    j := l_item.lower
                    nb_j := l_item.upper
                until
                    j > nb_j
                loop
                    ...
                    j := j + 1
                end
            end
            i := i + 1
        end
    end

Rescue Clauses

When adding a rescue clause with a retry a state variable, typically used to determine if a retry has been performed, there is no need to use a local declaration prefix. In fact, it's recommended there is no prefix. Instead just use a variable named retried:

perform
        -- An example using a rescue/retry local variable name.
    local
        retried: BOOLEAN
    do
        if not retried then
            ...
        end
    rescue
        retried := True
        retry
    end

Object Tests

Object test locals obey the same rules and other standard local declarations, that it, prefixing a variable moniker with </e>l_</e>. However, due to the current scoping rules of object-tests, where no object test local may be reused, extraneous guidelines need to be defined.

close
        -- An example using object-test scoped local variable names.
    do
        if {l_disposable: DISPOSABLE_I} Current then
            l_disposable.dispose
        end
    end

In Contracts

Object tests may need to be defined in contracts, especially when projects/libraries are configured to use Void-Safe compilation checks. To prevent variable name conflicts from arising a secondary prefix should be used to define an object-test local. Again using l_ but this time prefixed with the first character of the enclosing assertion clause. Such rules would dictated the following prefixes to be used in object-tests, for assertion clauses:

• rl_ for require
• el_ for ensure
• cl_ for check
• ll_ for loop
• il_ for loop invariant
• vl_ for loop variant

close
        -- An example using object-test scoped local variable names in contracts.
    require
        is_interface_usable: {rl_usable: USABLE_I} Current implies rl_usable.is_interface_usable
    do
        ...
    ensure
        not_is_interface_usable: {el_usable: USABLE_I} Current implies not el_usable.is_interface_usable
    end

Indexing

When a conflict between local delcarations exist a form of indexing must be use

equals (a_object: ANY; a_other_object: ANY): BOOLEAN