Modula-2 Standards

Naming - Indentation - Documentation

The most important thing of standards is being consequent, always using the same choices of naming, code structure, etc.
Your code will be easier to understand and to write, you will easier remember variable, type and procedure names.
So, we don't force you to use the following standards, it's ok if you create your own and follow them. Only be consequent.
The most commonly used (and widely accepted) standards are marked in bold.

Naming

Choose the names as follow:

MODULE ModuleName;

modules

start

with

a capital

CONST ARRAY_SIZE = 15; => constants: all capitals, seperated by underscores

    TYPE DayEn = (MON_DAY, TUE_DAY,...);=> enums: suffix 'En'
                               => enum constants: all capitals, seperated by '_'
                                                                                                    optional: use a unique suffix for that type

TYPE HoursSb = [0...24]; => subranges: suffix 'Sb'

TYPE CalendarAr = ARRAY[1..ARRAY_SIZE] OF DayEn;
=> types: suffix 'Ar'

          TYPE PersonRc = RECORD         => records: suffix 'Rc'
           namePerson: ARRAY[1..35] OF CHAR;  => record fields: start with small letter
               lengthPerson: CARDINAL;

END;

    PROCEDURE DoThis (inputVar: CARDINAL);
                                 => procedures: start with a capital
                                => parameters: start with a small letter
          VAR toReturn: INTEGER;
           nbr_items: CARDINAL;      => local variables: use underscores
    BEGIN
        ...
        RETURN toReturn;
    END Dothis;

PROCEDURE Calculate_Nbr(...) => local procedures: use underscores
...

    VAR gChoice: INTEGER;       => global variables: use prefix 'g'
         startHour: HoursSb;         => local variables (only used in the module or procedure): start with a small letter, each new 'word' with a capital
         partA_Parameter: HoursSb;   => use underscores between capitals
BEGIN
        ...
END ModuleName.

If you use your own standard and have to think about whether something is a constant, procedure, type or variable,
then your standard probably isn't very good.
Names should make clear what they represent and can be quite long

so don't use variablenames like a, b, c

exception: for indexes use i, j, k, l, ...

with good explanatory names not much extra documentation is necessary
example: PROCEDURE Give() (* returns the number of items chosen *) is bad, PROCEDURE NbrItemsChosen() is better

Use the following abbreviations:

Max, Min, Avg - to mean the maximum/minimum/average value something can have.
Cnt - the current count of a running count variable.
Key - key value.
Nbr - number
sz - size
Proc - procedure
Id - unique identifier

Create standard abbreviations for your project, for word & concepts (begrippen) you will use a lot

Indentation - Very Important!

Indentation is one of the most important ways to keeping long pieces of code readable. Without proper indentation, the program stucture is not visible and mistakes are easier to make and harder to trace!

Start a new line after every statement, except for write statements: you may group them on 1 line.

Indent with 2 or 3 spaces (or with a TAB - you can edit the tab size in the modula-2 editor to your own taste):

in a module or procedure

MODULE Bla;

IMPORT ...

VAR a:...

PROCEDURE Test(...);
VAR i:...
BEGIN

i := 1;

END Test;

BEGIN

a := Test...
WrStr...

END Bla.

in every loop

FOR i := 1 TO n DO

WrStr...

REPEAT ...

WrStr...

UNTIL..

END;

in an IF or SWITCH clause

IF .. THEN

CASE DAY OF

MONDAY:

WrStr(...

| TUESDAY:

...

ELSE

...

END;

...

ELSE

WrStr..

END;

Documentation

explain only the necessary

explain special, unexpected things

with good naming of variables and procedures, no extra explanation is necessary

eg PROCEDURE NbrItemsChosen() : don't add redundant documentation like " this procedure returns the number of Items chosen!"

Back to the top