ITEC 320 Style Guidelines

1. White Space
• Includes indentation, spacing, blank lines
• Use white space to enhance the readability of your program.
• Include a single space after colons and on each side of assignment and binary operators

  yourVariable: Integer;  -- (OKAY)
  theVariable : Character;  -- (OKAY)
  someVariable:Character;  -- (DON'T)

  myVariable := 2 * sqrt(3 + a(i) / 6);   -- (DO)
  myVariable :=2* sqrt(3+a(i) /6);   -- (DON'T)

• Be consistent


2. Line length
• Source file lines should be 80 characters or less.
• This includes comments
• I will translate tabs to 4 characters.
• Long lines should be broken at reasonable locations

  put("Some string" 
      & " and the rest of the string");

  if some_long_boolean_variable
     and some_long_integer_variable = another_long_integer
  then

    a := some_long_integer_variable
        + another_long_integer_variable
        + some_very_very_long_integer_variable; 



3. Header comments
• Each file must contain a header comment with
• your name
• the date
• the course
• a concise description of the file's purpose.
• information on help received

        -- Name: Rob Roberts
        -- Date: August 8, 2008
        -- Course: ITEC 320 Procedural Analysis and Design

        -- Purpose: This program implements a simple calculator.
        -- Input is a sequence of operations, one per line, until end of file.
        -- Each operation contains an integer, a space, an operator, a space, an integer, 
        --   and the equals symbol (ie '=').
        -- Valid operators are the following characters: +-*/
        -- Division gives an integer resul).
        -- Multiplication (division) is to be done by repeated addition (subtraction).
        -- Output is the operation, a space, and the result.
        -- Input is assumed to be valid.  
        -- Sample input:
        --     22 + 33=
        --  44 - 55=
        --     11 * 66=
        --       777 * 10=
        -- Corresponding output:
        -- 22 + 33 = 55
        -- 44 - 55 = -11
        -- 11 * 66 = 726
        -- 727 / -10 = -72

        -- Help received: I used material on for loops from www.someadapage.com 



• For each procedure or function, include header comments that
  • make it stand out
  • state its purpose
  • describe its parameters
  • describe its local variables
  • state any assumptions it makes about its parameters (ie its preconditions)
  • state its purpose (ie its postcondition)

          ----------------------------------------------------------
          -- Purpose: Performs multiplication by repeated addition 
          -- Parameters: x, y: values to multiply
          -- Precondition: x <= y
          -- Postcondition: Returns product of x and y
          ----------------------------------------------------------
          function multiply(x, y: Integer) return Integer is 

  
  
• In a package specification, the comments that describe a procedure header do not need to be repeated in the package body.


4. Line and Block comments
• Some individual lines need further explanation, which can be done with a comment on that line.
• A comment should not simply repeat the text of the code; instead it should describe the purpose of the statement(s) in terms of the problem you are trying to solve.

       number_of_people := number_of_people + 1;   -- add 1 to number_of_people  (DON'T)
       number_of_people := number_of_people + 1;   -- count people     (DO) 

• Each related group of statements within a procedure or function should have a comment that describes the purpose of that group of statements.


5. Variable and Parameter Declarations
• For each variable in each routine, including your main procedure, describe the purpose of that variable in a comment.
• Place these comments near the declarations of the variables.
• Your comment should describe the purpose of the variable in the context of the problem being solved.

        x, y: Integer;          -- Values from input
        small, large: Integer;  -- Sorted input values. small <= large
        answer: Integer;        -- Result of calculation 

• Procedures and functions should have comments that describe the purpose of their parameters (example above)


6. Names
• Choose meaningful names for types, variables, constants, procedures, functions, and packages.
• Use any names that are specified in your assignment, particularly for procedures, packages, and files.


7. Constants
• All numbers except 0, 1, and -1 in your program should be named constants.

    Number_of_Years := Number_of_Days / 365;               -- DON'T
    Number_of_Years := Number_of_Days / DAYS_PER_YEAR;     -- DO
    



8. Other Issues
• Use consistent capitalization.

   if myName /= yourNAME THEN      -- (DON'T)

   if myName /= yourName then      -- (DO)
   IF my_name /= your_name THEN    -- (DO) 

• Use constants, initialization, and other language features as appropriate.
• Do not use global variables.
• Style is normally worth about 25 points on a program.