Naming conventions

Interfaces

Interface names follow the "I"+verb convention common to .NET. Interfaces belong with their functional kin (as opposed to a separate Interfaces package). Consumers of these materials will extract the Interfaces if necessary, based on the naming convention (I*) or via the documentation (UML etc).

Rationale

Early iterations of the reference component code had interfaces in their own Interface package, per layer/component. One of the design goals is to be able to have the consumers of the reference components/OERI be able to extract the interfaces (and, as it turns out, any supporting classes like EventArgs) and use them as a foundation for their own code. So all of the packages have an Interfaces folder which - logically enough - contains all of the interfaces for that package.

There are a couple of hiccoughs with this approach:

  1. Interface members may reference objects other than other interfaces. For instance, OpenEdge.Core.EventArgs. We could add an IEventArgs but its only purpose would be to keep 'package purity'.
  2. Having one folder/package for all the interfaces means that we lose the separation of concerns to a degree: there might be interfaces for Model- and Presenter-related stuff in the one Interfaces package. This problem becomes worse the larger the codebase.
  3. Package bloat. Exacerbates the above.

Properties

Names

Properties names should be a descriptive name only, with no indication of data type. They should be PUBLIC. However, if the property is ABSTRACT, it can be PROTECTED or PRIVATE. Property names should never have underscores in their names.

Properties as constant values

Properties can be used as constant values. If so, the property should be defined as PUBLIC STATIC, and should be read-only or not have a public setter. If read-only, the value should be set via the INITIALphrase in the property definition.

Properties that are used as constant values, should be named in all caps (upper case), and can have underscores as word separators.

define public static property SOME_CONSTANT_VALUE as decimal init 3.14159 no-undo get.
Properties as enumerations

Properties are used as the members in enumerations. In this case, the data type will be OpenEdge.Lang.EnumMember. Names are in PascalCase, and the property usually has a private set; this setter is used in the static constructor to initialise the enumeration's member.

define public static property SomeEnumValue as EnumMember no-undo get. private set.

Member variables

These should be of the form m<datatype><Name>, where the datatype corresponds to a value in the table below.

Data typeName
o Progress.Lang.Object
e Progress.Lang.Error
c Character, Longchar
d Decimal
i Integer, Int64
t Date, Datetime, Datetime-tz
r Raw, Rowid
l Logical

Member variables should always be PRIVATE or PROTECTED; publically accessible members should be made properties.

Method-local variables

Variables defined within methods should have the form <datatype><Name>, where the data type matches the table above.

method public void DoSomething ():
  define variable cName as character no-undo.
  define variable oPresenter as IPresenter no-undo.
  /* code */
end method.
 

Method names

Method names should describe the function of the method, and should be in CamelCase (1st letter in caps). For instance,

GetInstance()

Access level

As a rule of thumb, member variables should be kept PRIVATE; conversely, any private members should be variables; properties are to be used when the access level is PROTECTED or PUBLIC.

One discussion at StackOverflow

Any PUBLIC members (i.e. properties, events, methods) should be defined in an Interface; as a rule, there should not be any public members in a class that are not in an Interface.

Package names

Package names should be in PascalCase (1st letter in caps). The package names follow the built-in ABL objects' convention, which is Progress. and is similar to the .NET convention.

For example,

OpenEdge.Reference.MyApplication.

Class names

Class names should be in PascalCase.

Usage conventions

Use of the USING statement

Using USING is strongly recommended - it makes code more readable and makes refactoring much easier.

Object initialization

Sample application objects will be initialised via a two-phase approach (3 if you include the constructor); this is managed by the InjectABL component.

Constructor

As a guideline, the constructor should not be used for much more that setting property/members to initial values, although the INITIAL phrase on the DEFINE statement can do this equally well, if the member is defined in the current type.

Constructors should never pass this-object to other objects or methods. They should not have a noticeable overhead.

There are some guidelines for constructor design at MSDN.

CreateComponent() method

Generally-peaking, the creation method will create dependent objects, and will set up object inter-dependencies. See also ...

Initialize() method

This method completes the object construction.

The use of an Initialize() method is also a Good Thing when it comes to

class foo inherits bar 
 
implements IComponent:
 
  constructor public foo():
    PropertyOne = 'some val'. // defined in bar
  end constructor.
 
  method public void CreateComponent():
    StartChildren().  
  end method.
 
  method public void Initialize():
    SubscribeEvents().
    FetchData().
  end method.
end class.

Documentation Comments

Method and class/file comments should be formatted according to the  AutoDox2 format. From the documentation:

A comment doc begins with /** followed by at least one whitespace character. (i.e. /*** would not begin a comment doc.)

  • First comment line is treated as the summary.
  • Between the summary line and the first @tag is the 'remarks' section.
  • The @tags section comes at the end.

Any valid HTML can be embedded into the summary, remarks, or tags.

Sample input:

    /** The first line is the summary.
      * If I knew what this was for, I would
      * write <b>lots</b> about it here.
      * <p>
      * And I'd have another paragraph about it here.
      * Note that hyperlinks are allowed:
      * Visit <a href="http://www.joanju.com/">joanju.com</a>!
      * @ArbitraryTag Arbitrary tag names are allowed.
      * @author John Green, August 2009
      * @param pcType Test one two three
      * @param phTT Test four five
      * @return Nothing!
      */
Output:
The first line is the summary.

If I knew what this was for, I would write lotsabout it here.

And I'd have another paragraph about it here. Note that hyperlinks are allowed: Visit joanju.com!

Author:
John Green, August 2009
ArbitraryTag:
Arbitrary tag names are allowed.
Parameters:
pcType - Test one two three
phTT - Test four five
Returns:
Nothing!

Recognized Tags

  • @author
  • @deprecated
  • @param
  • @return

The first word after @param is treated as the parameter name. All other tags are treated simply as a line of text.