CS152, Fall 2020

Computer Programming Fundamentals, Code Style Guidelines
Home
Schedule
Syllabus
Style Guidelines

Description

All organizations and companies have conventions for formatting code.  While these formatting rules vary from place to place, they are important for making your code readable and for enabling others (and you) to understand and use your code in the future. 

We will be using the following coding standards in our class.  Following these standards will be a portion of your grade on each programming assignment.

Naming Stuff

• Use meaningful and descriptive names. For example, if your program needs a variable for the radius of a circle, call it radius, not r.
  
• Avoid the use of single letter variables (like r). Use them mostly for simple for or while loops.
• Begin variable and function names with lowercase letters
• Begin class names with uppercase letters
• Use all uppercase letters for constants (i.e., float PI = 3.14;)
• Be consistent.
• Separate words within names with mixed upper and lowercase. For example:
• Variables: grandTotal, circleRadius
• Functions:  computeArea, saveFile
  
• Classes:  CircleTable, PieChart

Space
The most readable programs are written with good use of "whitespace". Whitespace includes blank lines, tabs, and spaces. Before you hand in an assignment, take a look at your code and ask yourself "Does this look organized? Can I read this?" Use the "Auto Format" tool under the "Edit" menu in Processing for some help with this.

• Use blank lines to separate major parts of a program.
• Separate variable declarations from executable statements with a blank line.
• Header comments and top level function calls and class names begin all the way to the left of the page. All statements within these class names and function calls are indented.
  
• All statements in the body of a function are indented beyond the function definition.  Statements inside of a loop or part of an if structure are indented further.
• Use spaces around all operators. For example, write "x = y + 5;" instead of "x=y+5;"
  

Comments
Header Comments
Every program you write should contain a header comment that describes the program and includes other important information.  It must include the following information:

• The assignment number
• Your name
• Your UNM e-mail address
• The class and section number
• The date the assignment was submitted
• A description of your program

For example:

Comments in Your Code
A good rule of thumb is that you should be able to delete all of your code and then regenerate a working program from the comments.

• Comments explain what your code does; they do not describe how it does it.
• Well-structured code should be broken into sections that perform a simple task. Each of these sections of code should be commented.
• A particularly important line of code should also be commented.
  
• Do not comment every line of code.  Trivial comments (i.e., //add one to x) aren't helpful.
  

An in-line comment appears above the code to which it applies and is indented to the same level as the code. For example:


Endline comments appear immediately after a line of code, on the same line. These should be used rarely and only to explain special aspects of a line, such as what a variable means or some unusual feature of the code:
   

 

Indentation Styles

Choose one of the two styles below and use it consistently

if (condition) {                                     if (condition)
    ...                                              {                    
} else if (condition) {                                  ...
    ...                                              }
} else {                                             else if (condition)
    ...                                              {
}                                                        ...
                                                     }
                                                     else
                                                     {
                                                         ...
                                                     }


for (loop control expressions) {                     for (loop control expressions)
    ...                                              {
}                                                        ...
                                                     }


while (condition) {                                  while (condition)
   ...                                               {
}                                                        ...
                                                     }


do {                                                 do
   ...                                               {
} while (condition);                                     ...
                                                     } while (condition);
                                                    

switch (variable) {                                  switch (variable)
   case constant1:   ...                             {
        break;                                           case constant1:   ...
   case constant2:   ...                                      break;
        break;                                           case constant2:   ...
   case default:     ...                                      break;
}                                                        case default:     ...                                                      }


Note: This document is adopted from Bryn Mawr's CS110 Style Guidelines.