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).
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:
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 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 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.
These should be of the form m<datatype><Name>, where the datatype corresponds to a value in the table below.
Member variables should always be PRIVATE or PROTECTED; publically accessible members should be made properties.
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 */
Method names should describe the function of the method, and should be in CamelCase (1st letter in caps). For instance,
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 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.
Class names should be in PascalCase.
Using USING is strongly recommended - it makes code more readable and makes refactoring much easier.
Sample application objects will be initialised via a two-phase approach (3 if you include the constructor); this is managed by the InjectABL component.
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.
Generally-peaking, the creation method will create dependent objects, and will set up object inter-dependencies. See also ...
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
constructor public foo():
PropertyOne = 'some val'. // defined in bar
method public void CreateComponent():
method public void Initialize():
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.)
Any valid HTML can be embedded into the summary, remarks, or tags.
/** The first line is the summary.
* If I knew what this was for, I would
* write <b>lots</b> about it here.
* 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!
And I'd have another paragraph about it here. Note that hyperlinks are allowed: Visit joanju.com!
The first word after @param is treated as the parameter name. All other tags are treated simply as a line of text.