- 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
- 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;
- 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.
- 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.
- 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)
- 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.
- 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
- 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.