2.1.1. Business Objects

Comments about what should be changed in this document (and what is even missing) are very appreciated, because every comment possibly reflects on future versions of this document and therefore will make the final document better. Please direct your comments to Neil Tiffin (neilt@gnue.org).

This chapter was originally written by Neil Tiffin (neilt@gnue.org) and comes from documents and code originally written by Andrew Murie (andrewm@gnue.org) and coding standard from Reinhard Müller(reinhard@gnue.org). Some examples contributed by Stanley A. Klein.

GNUe business objects are defined in GNUe Class Files (GCD). These files have the extension ".gcd". This chapter discusses the format of GCD files. Business objects are processed by the GEAS server. If you are using GNUe Forms in 2-tier mode then things work a little differently.

This document contains only definitions that are implemented in geas now or noted specifically as not implemented. Names in CAPITALS are literal words for the purpose of this document. More technical information may be present in the geas document directory in cvs.

2.1.2. Naming Conventions

All names must start with an alpha character and contain only characters, numbers, and the "_" character. Names may not contain two "_" characters together (e.g "__") and may not end with the "_" character.

The GCD syntax does not care about upper or lower case so all names should be written in lower case.

Words in names should be separated by a single "_" character.

2.1.3. Coding Conventions

1. All words, reserved words (class, module...) as well as identifiers (person, given_names...) are written all in lowercase, because lowercase is easier to write.

2. Class definitions start at column 1, and the "{" is on its own line. This will probably enable some emacs magic (we would have to adapt the c-mode a little bit for ignoring the "module"-line). Would need an emacs expert for that.

3. The first line of all files is blank. This is required because docbook may not start a new line when including the file in the documentation.

4. Lines are wrapped at 72 characters. Docbook will automatically wrap the lines and it does not look right.

5. Use 2 character indenting, as this is GNU standard.

6. The "*" is after the whitespace, just like normal c coding style.

7. Beginning of all identifiers are in line for each class ("person" and "*type" start at the same column).

8. Don't duplicate the module name in a class. That means that we don't use class names like "person_type" in a module "person", but we user rather "type". Module "person", class "person" and field "person" is ok.

9. Don't duplicate the class name in a field. Don't use "type_code" as a fieldname in a class "type", but we use just "code". Module "person", class "person" and field "person" is ok.

10. Every file should have a second line that contains the filename and a short (one-line) explanation what this module is for. The filename should utilize the cvs keyword substitution string. For example: "# $RCSfile: businessobjects.html,v $ - then the one line description of the file."

11. Every type, class and extend definition should be preceded by a one-line comment that tells what this type/class is for. I am a fan of having such comments surrounded by lines.

12. Module names and class names are always singular. It is hell to remember whether the class is called "phones_numbers", "phone_numbers", "phones_number" or "phone_number".

13. Field names are always singular, except list references are always plural.

14. Similar fields in different classes should have the same field name. If names are like employee::surname, customer::last_name, and supplier::lastname, this will drive every consultant crazy :)

15. Types should be generic types (type code_t = char<8>;) rather than specific types (type person_code_type).

An example:

module person
{

  # -------------------------------------------
  # common definitions for persons
  # -------------------------------------------
  type person
  {
    char surname<35>;
    char given_names<35>;
  };
  
  # -------------------------------------------
  # types of persons
  # -------------------------------------------
  class type
  {
    char code<8>;
    char description<35>;
  };
  
  # -------------------------------------------
  # employees
  # -------------------------------------------
  class employee
  {
    person::person *person;
    person::type   *type;
  };

}; # end of module