Difference between revisions of "Local Declaration Guidelines"

Revision as of 12:02, 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 Routine Arguments

When working with an in-line agent, to prevent conflicts with the enclosing routine's arguments, the prefix ia_ should be used. The same rules regarding English language rules apply here as they do to routine 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

Indexing Routine Argument Variable Names

In rare cases there is a need to use the same name on a routine's arguments, which of course no useful language would allow. Instead a slight form of indexing needs to be applied. In this case the use of other embedded in the variable name would suffice for most cases.

compare_strings (a_string: READABLE_STRING_GENERAL; a_other_string: like a_string): INTEGER_8
        -- An example using 'other' to index the second routine argument name
    do
        ...
    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 BASIC'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

No prefix, other than l_ is needed for class invariants because no conflicts in variable name reuse exist in an invariant scope.

Indexing

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

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