Operating Systems Principles
Preliminary CSAI Coding Standards
Last updated Wed. 1/28/2014
Back to CSAI home page
Back to Reva Freedman's home page
Summary
Coding standards, including formatting and documentation are
important because the human reader is one of the most important users
of program source.
These rules have been set up to create the most clarity while
reducing redundant documentation as much as possible.
Corrections and suggestions are invited.
Program Organization
Overall Program Formatting
Line width should be optimized for the human reader. Therefore
in general lines should not exceed 78 characters.
This applies to comments as well as code.
Consistency is more important than any specific rule.
Program Header
A header similar to the following should appear at the top of
your main program:
# Class: CSCI 490-B3
# Program: Assignment 1
# Author: Your Name
# Z-number: z1234567
# Date Due: mm/dd/yy
# Purpose: A short indication of what the program does
# Execution: Command to execute your program, e.g., ./hw1.exe
# (should match directions on assignment sheet)
# Notes: (optional) any special notes to your T.A. or other readers
Format of Names
Names of variables and functions may use one of two
formats:
- Underscores, e.g.,
avg_height.
- Camel case, e.g.,
avgHeight.
Name format should be consistent within a program.
Variable Names
In general, the base of a variable name should be a noun, with
adjectives used to make it specific, e.g., avg_height.
Names should be descriptive, e.g., avg_height rather
than h or hgt.
In general, abbreviations should be avoided; as above,
height is preferable to hgt.
Abbreviations can be useful for long or frequently repeated
words.
If abbreviations are used, they must be
spelled consistently throughout your program, i.e., if you use
avg_height for average height, then you should use
avg_weight for average weight and not ave_
or average_.
Temporary variables
The exception to this rule is for temporary variables that have no
intrinsic meaning, such as subscripts and loop counters.
Symbolic constants
Function Names
In general, function names should start with a verb and state what
that verb refers to, e.g., count_lines().
The same rules on abbreviations for variable names apply to
function names as well.
Comment Format
Section Documentation
Each section of code should be preceded by a comment that explains
what the code does or what that group of variables is used for.
The following examples show the size of chunk
that should be commented.
# Loop to accept and process user-supplied glucose measurements
# Decide if gizmos or widgets are to be used
# Calculate and store averages and standard deviations of measurements
Some programs are longer or more complex
than others. That means that your main program may have several sections
while a function that only does one thing may have only one.
Occasionally, for a complex formula, a
section will be only one line long:
# calculate the area of the triangle: semi is semiperimeter
# s1, s2, and s3 are sides
area = sqrt(semi * (semi - s1) * (semi - s2) * (semi - s3))
Section documentation should be preceded and followed by a
blank line. Additional blank lines before logical divisions of the
program and before functions may be profitably used to indicate the
structure of the program. Be consistent.
Section documentation should always start in column 1.
It is rarely but occasionally useful to put a comment on the same
line as code.
... # end I/O loop
If you find yourself frequently needing such
comments, you should consider changing your nesting style.
Documentation of variables
Even though variables don't need to be declared in Python, they
still need to be documented. Variables should be organized into
groups at the top of each function (or main program), and each group
should be labeled as to their purpose:
# Item subtotals
# tot_items = total number of items
# tot_cost = total cost
Horizontal alignment of variable names, as
in the above examples, is encouraged but not required.
Indentation
Fortunately, Python requires indentation to run correctly, so
detailed rules on indentation aren't required.
Indentation of 4 spaces per level is suggested.
Continuation lines
Tabs and spaces
Spaces are better than tabs for indenting because they will display
correctly in any configuration.
Any good editor will have a setting that prevents spaces from being
converted to tabs.
If you use tabs, you are responsible for making sure your program
will display correctly on turing/hopper. Unix defaults to tabs every 8
characters.
Horizontal white space
White space should be used before and after '=' and comparison
operators ('= =', '<', etc.):
Do not put white space after a left parenthesis, bracket or
brace, or before a right parenthesis, bracket or brace.
Functions
Functions should be documented like sections, plus some
indication of the arguments and return value. If the function updates
one or more of its arguments (or values they point to), that should be
noted also.
# Calculate the area of a triangle using Hero's formula
# Arguments: sides of the triangle
# Returns: the area of the triangle
# -1 if the lengths do not represent a valid (closed) triangle
# Additional section documentation as required.