Difference between revisions of "Eiffel Code Comments"

Revision as of 03:15, 27 August 2009

Comment Mark Up

The Eiffel compiler and EiffelStudio's code browsing tools support a special, light-weight mark up in comments and strings for referencing classes and features. EiffelStudio's code browsing tools utilize this mark up to better facilitate code navigation and browsing. In addition, marked up comments and strings will be examined and altered when performing a class or feature _rename_ refactoring.

Syntax

The syntax for marking up classes and features is very compact, to ensure retained legibility. You'll see no need for XML or other types of verbose mark up found in other languages, which can impede the comment's very nature as a quick reference.

To mark up a class reference, surround the class name in an open ({) and matching closing (}) brace:

-- See {DEBUG_OUTPUT} for more information.

To mark up a feature reference, implemented in the same class or parent, surround the feature name in a single back quote (`) and a matching closing single quote ('):

-- See `debug_output' for more information.

In the case where a reference to a feature is not accessible to the containing class directly, use a combination of the class reference mark up and a feature name, _sans_ quotation marks:

-- See {DEBUG_OUTPUT}.debug_output for more information.

The rules that apply for comments, as described above, can also be utilized in any manifest or verbatim string:

note
    description: "Augments searching facilities of {STRING_8}"

Precursor Comments

Minimum EiffelStudio Version: 6.2

Precursor comments declarations are a new mechanism added to EiffelStudio 6.2 to replicate a parent feature declaration's comments in the redefined/effective feature. The purpose of the mechanism is to reduce comment duplication, ease comment maintenance and facilitate augmentation.

For the purpose of demonstration, take the following deferred interface:

deferred class
  BASE
 
feature -- Query
 
  test (a_arg: INTEGER): BOOLEAN
      -- Comments for a feature.
      --
      -- `a_arg': An integer value.
      -- `Result': Could be True or False.
    deferred
    end
 
end

And effective implementation of it:

class
  TEST
 
inherit
  BASE
 
feature -- Query
 
  test (a_arg: INTEGER): BOOLEAN
            -- <Precursor>
        do
        end
 
end

TEST instead of replicating the comment makes use of the precursor comment declaration (-- <Precursor>), which supporting code browsing tool will expand to show the precursor feature's contracts. The declaration is optional but is only supported for existing code out there that do not have comments due to lax implementation. Even though optional, it is strongly recommended that you use -- <Precursor> comment declaration, as it indicates to any reader the feature is a redefinition or effective implementation of a parent feature declaration.

Comment Augmentation

The precursor comments declaration also supports augmentation. All a comment author has to do is to write additional comments before and/or after the precursor comment declaration. As a requirement, the precursor comment declaration must appear on a separate line for no other purpose except for clarity. Failure to do so will results in the rendering of the comments as they are declared in the feature, i.e. with -- <Precursor> as is.

test (a_arg: INTEGER): BOOLEAN
    -- Comments before the original comments from {BASE}.
    --
    -- <Precursor>
    --
    -- Some additional comments.
  do
  end

Using the code browsing facilities of EiffelStudio the reader will be presented with an expanded comment, for the effective version of feature test, that now read

-- Comments before the original comments from {BASE}.
--
-- Comments for a feature.
--
-- `a_arg': An integer value.
-- `Result': Could be True or False.
--
-- Some additional comments.

For clarity it is a good idea to separate the agumented comments from the precursor comment declaration. Using the same example above but removing the one line spacing above and below the precursor comment declaration would results in the following, less readable comment:

-- Comments before the original comments from {BASE}.
-- Comments for a feature.
--
-- `a_arg': An integer value.
-- `Result': Could be True or False.
-- Some additional comments.

However, that said, it is pure discretion to use additional spacing or not. Some situation do not call for, other do and some might (when the original comment changes.)

Multiple Redefinitions and Selection

With Eiffel supporting multiple inheritance, a scenario will arise where two inherited redefine features are joined in a descendant.

By default the precursor comment declaration is replaced by the first located inherited feature comment, which may cause documentation irregularities. Because precursor comments are not signification to compilation they are not checked during compilation, such as is the way with the use of Precursor, resulting a compile time error when not selecting the parent class to call into. This can cause documentation irregularities because there is no guarantee that they feature comments viewed one project will be the same in another.

To facilitate correct documentation the precursor comment declaration can use an optional select clause, just like using Precursor in the Eiffel code.

f (a_arg: INTEGER): BOOLEAN
        -- <Precursor {BASE}>
     do
     end

This will have exactly the same effect as using -- <Precursor> when f is made effective/redefined from a single parent. However, when making effective/redefining from multiple parents then comments will come from the parent class declaration in BASE.

Again, because precursor comments do not affect compilation they are not checked at compile time. Specifying an incorrect class will yield a warning message in EiffelStudio's code browsing tools, to the effect:

-- Unable to retrieve the comments from redefinition of {CLASS_NAME}.

Library Documentation Generation

Precursor comments are supported in all code browsing/documentation facilities, whether is be the integrated Contract Viewer, the Feature Relation Tool or the Eiffel documentation generation facilities. Using -- <Precursor> will ensure the comments are brought up from a parent declaration.