You are responsible for reading and adhering to the entire the Python Style Guide for CS-241. Since the guide is rather long and provides a number of specific examples, this page summarizes the requirements. For each of the following items (which appear in no particular order), be sure to fully read the related section(s) in the guide.
Documentation
Comments are used to help the reader of your source code. Your comments should written assuming the reader is a progammer that knows Python, but does not know the problem you are trying to solve.
- Include a file prolog in every module. It must begin in the first column and must include the name of the file, your name, the section number and a description of the file contents.
- Every function and method must have a prolog that briefly describes the purpose of that function or method. It should be placed above the function or method header. The only exception is the
main() function which is typically described as part of the file prolog.
- If a module contains more than one class definition, each class must be documented. If there is only one class in the module, the file prolog will be sufficient.
- Code segments (blocks of code) that are not obvious to the reader must be commented. Use inline comments to document the individual steps of an algorithm.
- Limit the use of side bar comments.
- No comment should be unindented (sticking out to the left) of the item being documented. For example, when documenting a function, the comment must begin in or after the same column as the
def keyword.
- DO NOT use strings for comments.
Program Structure
All of your modules should be well structured.
- When using functions in the driver module, you must include a
main() function (listed first) and there can be no executable statements outside of functions (other than initializing constant variables).
- The driver module may not contain any class definitions unless explicitly stated otherwise.
- A module that implements an ADT may not contain function definitions or executable code outside of the class definition (and its methods)
- Helper methods must be private and must be listed at the end of the class definition.
- You are not allowed to use global variables (other than non-constant variables). Data should be passed via functions.
Statement Structure
Readability
All of your code should be easy to read when printed on letter size paper in a normal font (10 or 12 point).
- Leave spaces around operators.
- Leave at least one blank line between every function and method.
- Leave a blank line before an inline comment except when the inline comment is the first line within a function or method definition.
- Long lines must be explicitly wrapped for easy reading.
Naming
You must use meaningful names for all identifiers and they must follow the naming conventions.
- Use camel case notation for all non-constant variable identifiers.
- Non-constant variables must begin with a lowercase letter.
- Class names must begin with an uppercase letter.
- Constant variable names must consist of all uppercase letters with words separated by an underscore.
- Data attributes (for non-storage classes) must be defined as private (name begins with a single underscore).
- Helper methods must be defined as private (name begins with a single underscore).
Restrictions
While Python allows instructions to be written in a variety of ways, good programming style dictates some things that you should not do.
