Tutorial: Quorum Coding Conventions

Conventions for naming classes, actions, and parameters

We recommend the following conventions for naming classes, actions, and parameters in Quorum: Do's:

• Do use short and meaningful names
• Do use names that are common in English
• Do use names that best represent what it is your class, action, or parameter does or is
• Do use the most obvious name you can think of for your libraries (a thesaurus is helpful).

Do not's:

• Do not use acronyms (e.g., awk, sed, ascii, io)
• Do not use shortened names (e.g. use AbsoluteValue instead of Abs, or CharacterToInteger instead of atoi)
• Do not use single letters for parameter names (e.g., use index instead of i)
• Do not use computer science or technical jargon (e.g., virtual void abs() = 0;, BTree, or LinkedList)
• Do not make names excessively verbose (e.g., ThisActionIsReallyAwesomeButHardToType())
• Do not give your libraries arbitrary names (e.g., call your library MailServer instead of BobsGem)

Naming and Layout Conventions

In Quorum, there are a few conventions for class, action and variable naming that we recommend following in your code.

Class Names

Class names in Quorum should be in the pascal case format, e.g., PascalCase, with the P and C capitalized.

Action Names

Action names in Quorum should also be in the pascal case format, e.g., PascalCase, with the P and C capitalized. In addition, actions that do not have any parameters do not require parentheses. By convention, leave out any syntax that is not required.

Variable Names

Variable names in Quorum should follow the camel case format, e.g., camelCase, with the first c lowercase and the second C capitalized.

Indentation

The Quorum compiler does not pay attention to whitespace in code. However, we ask that you use consistent indentation. Consistent indentation:

class Main
    action Main
        output "hello world."
    end
end

Inconsistent indentation:

class Main
action Main
output "hello world."
    end
end

Comments and Documentation

In Quorum, there are two types of comments: single line and multi-line comments. For single line comments, we recommend a space after the beginning two forward slashes, like so: Good single-line comment:

// Output a message to the user.
output "hello world."

Multi-line comments should be formatted such that the beginning forward star and ending star forward are on their own lines, like so:

/*
the main entry point to the program
*/
action Main
end

However, if on only one line, as a single line comment is sufficient:

/* May as well use a single line comment */
action Main
end

Documentation

Please fully document each action and class in Quorum standard library files. In each case, please be sure to include at least one example, in all case, of code to execute that action or use that class. Here is an example comment from the array class:

/*
The Array class is a data structure that stores items in contiguous memory. An
item is typically stored and accessed through an index or location. This location
always starts at 0, this means the first item in the array is at location 0, the
second is at location 1, etc. The default maximum size is set to 10, but can be
changed by using the SetSize(value) method or the array will automatically
make itself large when the space is needed (note: it is possible to turn the 
resizing off with the SetAutoResize(false) method).

Attribute: Example

use Libraries.Containers.Array
class Main
   action Main
      //make the array
      Array myArray
      //add a value
      myArray:Add(12)
      //get it back
      integer value = myArray:Get(0)
   end
end
*/

Next Tutorial

In the next tutorial, we will discuss Using Libraries, which describes how to use classes built into Quorum..