Programming
style deals with the appearance of your program. Documentation
consists of explanatory remarks and comments for the program. Good programming style and
appropriate documentation reduce the chance of errors and make programs easy to
read. This handout provides more detailed guidelines on programming style and
documentation that supplements the brief guidelines presented in Chapter 1,
First, here is a sample code:
'''
* Class: CSCI1301-03 Introduction to Programming Principles
* Instructor: Y. Daniel Liang
* Description: (Give a brief description for Exercise 1)
* Due: 1/18/2010
* I pledge that I have completed the programming assignment independently.
I have not copied the code from a student or any source.
I have not given my code to any student.
Sign here: __________
'''
# Enter radius of the cylinder
radius, length = eval(input("Enter the radius and length of a cylinder: "))
area = radius * radius * 3.14159
volume = area * length
print("The area is " + str(area))
print("The volume of the cylinder is " + str(volume))
Include a
summary at the beginning of the program to explain what the program does, its
key features, and any unique techniques it uses. In a long program, you should
also include comments that introduce each major step and explain anything that
is difficult to read. It is important to make comments concise so that they do
not crowd the program or make it difficult to read.
Make
sure that the meanings of the descriptive names you choose for variables,
constants, classes, and methods are straightforward. Names are case-sensitive.
Listed below are the conventions for naming variables, functions, and classes.
·
For variables and functions, always use lowercase. If the name
consists of several words, concatenate them into one, making the first word
lowercase and capitalizing the first letter of each subsequent word in the name;
for example, the variables radius and area and the method readDouble.
·
For class names, capitalize the first letter of each word in the
name; for example, the class name GeometricObject.
·
All letters in constants should be capitalized, and underscores
should be used between words; for example, the constant PI and constant
MAX_VALUE.
·
Use singulars for variables representing single items such as student
and count. Use plurals for arrays or collections. For example,
students =
[] and counts = []
TIP: It is important to become familiar
with the naming conventions. Understanding them will help you to understand Java
programs. If you stick with the naming conventions, other programmers will be
more willing to accept your program.
TIP: Do not choose class names that are
already used in the Python library.
A
consistent indentation style makes programs clear and easy to read. Indentation
is used to illustrate structural relationships among the program’s components
or statements. You should indent each subcomponent or statement four spaces
more than the structure within which it is nested.
Use
a space to separate parameters in a function. Do not leave spaces before or
after parentheses in a method. For example, aMethod(a1,
a2) is preferred, whereas aMethod ( a1, a2 ) is not a good style.
A single space should be added on both sides of a binary operator,
as shown in the following statement:
b = 3 + 4 * 4 > 5 * (4 + 3) - i
A
single space line should be used to separate segments of the code to make the
program easier to read.