Coding standards - UMBC-CMSC104/General GitHub Wiki

Every programming department has some set of standards or conventions that programmers are expected to follow. The purpose of these standards is make programs readable and maintainable. After all, you may be the programmer who maintains your own code more than six months after having written the original. While no two programming department's standards/conventions may be the same, it is important that all members of the department follow the same standards. Neatness counts!!! At UMBC, the following standards have been created and are followed in CMSC 104.

Part of every project grade is based upon how well these standards are followed.

It is your responsiblity to understand these standards. If you have any questions, ask your instructor!

##Naming Conventions Use meaningful variable names!!
For example, if your program needs a variable to represent the radius of a circle, call it 'radius', NOT 'r' and NOT 'rad'. The use of single letter variables is forbidden, except as simple 'for' loop indices. The use of obvious, common, meaningful abbreviations is permitted. For example, 'number' can be abbreviated as 'nr' as in 'nrStudents'.

• Begin variable names with lowercase letters
• Do not use global variables.
• Be consistent!
• Separate "words" within identifiers with underscores or mixed upper and lowercase. Examples:
• • 2-"word" variable name: grandTotal or grand_total
• • 2-"word" function name: ProcessError or Process_Error

The prudent use of whitespace (blank lines as well as space) goes a long way to making your program readable.

• Use blank lines to separate major parts of a source file or function.
• Separate variable declarations from executable statements with a blank line.
• Use 2 or 3 spaces for each level of indentation
• Indent statements inside of a loop or part of an "if" structure.
• Use spaces around all operators. For example,
• x = y + 5; NOT x=y+5;

Always use braces to mark the beginning and end of a loop or "if" structure, even when not required.

Choose one of the following two styles:

if (condition)
{
   statement(s)
}

if (condition) {
   statement(s)     
}        

if (condition)
{
   statement(s)
}
else if (condition)
{  
   statement(s)
}
else
{
   statement(s)
}

if (condition) {
   statement(s)
} else if (condition) {  
   statement(s) 
} else {
   statement(s)
}

for (loop control expressions)
{
   statement(s)
}

for (loop control expressions) {
   statement(s)
}

while (condition)
{
   statement(s)
}

while (condition) {
   statement(s)
}

do
{
   statement(s)
} while (condition);

do {
   statement(s)
} while (condition);

switch (expression)
{
   case value1:
       statement(s)
   case value2:
       statement(s)
   default:
       statement(s)
}

switch (expression) {
   case value1:
       statement(s)
   case value2:
       statement(s)
   default:
       statement(s)
}

Comments are the programmers main source of documentation. Comments for files, functions and code are described below.

EVERY project file should contain an opening comment describing the contents of the file and other pertinent information. This "file header comment" MUST include the following information.

• The file name
• Your name
• Your username
• The date the file was created
• A description of what the program does

For example,

/*   File: hw3.c
     Name: A. Student
     Username: astudent1
     Date: 10/24/07
     Description:  This file contains a program that gets two numbers from the
                   user and displays some statistics about the numbers.
*/

Function Header Comments EACH FUNCTION must have a header comment that includes the following: function name a description of what the function does a description of the function's inputs a description of the function's outputs side effect(s) of the function (if any -- this should be rare) For example: /************************************************ ** CircleArea -- ** This function calculates the area of a circle ** with the specified radius ** Inputs: the circle's radius as a parameter ** Output: the circle's area as the return value **************************************************/

"In-line" comments are used to clarify what your code does, NOT how it does it. Well structured code will be broken into logical sections that perform a simple task. Each of these sections of code (typically starting with an 'if' statement, or a loop or a 'switch') should be documented. A particularly important line of code should also be commented.

Do not comment every line of code. Trivial comments (/** increment x **/) are worse than no comments at all. An in-line comment appears above the code to which it applies and is indented to the same level as the code. For example:

/* Get and convert the radius from the user */
radius = prompt("Please enter the radius: ");
radius = parseFloat(radius);

Variables may be commented with end-line comments IF THEY ARE DEFINED ONE PER LINE as in the example below.

int total;        /* total students this section */
double average;   /* class's final exam average  */

You do not have to comment every variable. If the name is descriptive enough, it is not necessary to comment. In the above example, a comment would not have been necessary if the variables had been named totalStudents and finalExamAvg.