View source for Local Declaration Guidelines

You do not have permission to edit this page, for the following reasons:
The action you have requested is limited to users in one of the groups: Autoconfirmed users, emailconfirmed, editors.
You must confirm your email address before editing pages. Please set and validate your email address through your user preferences.
You can view and copy the source of this page:
{{UnderConstruction}}
[[Category:Coding Style Guidelines]]

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

== Feature Arguments ==
Feature arguments should begin with the prefix <e>a_</e> and nothing more. The prefix <e>a_</e> 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:

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

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

=== In-line Agent Routine Arguments ===
When working with an in-line agent, to prevent conflicts with the enclosing routine's arguments, the prefix ''<e>ia_</e>'' should be used. The same rules regarding English language rules apply here as they do to routine arguments. The ''<e>ia_</e>'' prefix represents an ''In-line Argument''.

<e>
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
</e>

=== 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 ''<e>other</e>'' embedded in the variable name would suffice for most cases.

<e>
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
</e>

== Local Declarations ==
Routine local declaration should also be prefixed to prevent potential conflicts between routine arguments or class attributes. The prefix ''<e>l_</e>'' 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 ''<e>i</e>'' should be use to indicate it is an index variable. Additional index variables should follow alphabetically from ''<e>i</e>'' 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 ''<e>l_count</e>'', a number-of-items variable will use a well-known contracted variable name '<e>nb</e>''.

<e>
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
</e>

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 [http://en.wikipedia.org/wiki/BASIC BASIC]'s <code>NEXT x</code> instruction:

<e>
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
</e>

==== Rescue Clauses ====

When adding a rescue clause with a retry a state variable, typically used to determine if a <e>retry</e> 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 ''<e>retried</e>'':

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

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

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

==== 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 ''<e>l_</e>'' 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:
* ''<e>rl_</e>'' for <e>require</e>
* ''<e>el_</e>'' for <e>ensure</e>
* ''<e>cl_</e>'' for <e>check</e>
* ''<e>ll_</e>'' for <e>loop</e>
* ''<e>il_</e>'' for loop <e>invariant</e>
* ''<e>vl_</e>'' for loop <e>variant</e>

<e>
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
</e>

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

== Indexing Variable Names ==
There will be times when variable names clash with one another and there is no choice but to apply the last-stop effort to naturally indexed variable names to suit. This last-stop effort is really a last-stop. Other attempts should be made to create unique variable names before applying natural indexing.

Natural indexing concerns itself with suffixing variables with a sequential natural index. The only exception is the first local declaration which may or may not have the primary index suffix ''<e>_1</e>''. To better illustrate, the following code examples are both valid uses of natural indexing:

<e>
perform
        -- An example of using natural sequential indexes to avoid variable name clashes.
    local
        l_item_1: ITEM
        l_item_2: ITEM
        l_item_3: ITEM
    do
        ...
    end
</e>

or

<e>
perform
        -- An example with the first index elided, which is also valid.
    local
        l_item: ITEM
        l_item_2: ITEM
        l_item_3: ITEM
    do
        ...
    end
</e>

If local declaration have to be indexed when first writing the code then it is far better to be explicit and use a natural sequential index for all similar local declaration (the former example). The latter example is valid and would exist when modifying existing code. There is no hard or fast rule here, each is valid as long as the indexes are sequential.

The examples apply to all variable declaration, not just local declarations.
Return to Local Declaration Guidelines.
Retrieved from "https://dev.eiffel.com/Local_Declaration_Guidelines"
View source for Local Declaration Guidelines

Navigation

Development

Wiki

Search

Tools
