CSCI 1300, Section 100
Style Guide


We owe thanks to Professor Michael Main who assembled the software package that we use for CSCI 1300 as well as the documentation and style guide he has put together.


The complete CSCI 1300/2270 Programming Style Guide is shown below. The most important issues (which we'll always grade on!) are:

CSCI Complete 1300 C++ Style Guide

In order to allow easy reading and understanding of everybody's programs, and to avoid risky programming practices, all software organizations have guidelines that programmers must follow. This page contains the guidelines we require you to follow in CSCI1300. For your interest, you might also look at some a real-world programming stylesheets.

At the same time, this page defines abbreviations that we can use in providing feedback to you on your programs. For example, if we mark II on a program you turn in, this sheet tells you that we think you have used incorrect indenting.

So, here's a list of bad things we'll be looking for in your programs, and the abbreviations we'll use to notify you if we find them.

These first two items are not really programming style rules. Instead they are rules about how to design, implement and test your programs. These rules are so important that if you ask for any help without following these rules, you will be sent away until you can show that you have met these rules.

RULE 1: Incremental Development and Testing

Never implement more than 20 to 30 lines of code without stopping, compiling, and checking that the program works correctly for the code that you have written so far. If you ask for any help from an instructor, then you must provide both the previous version of your program (with no known errors in it) and the current version (with an error, but with no more than 20 new lines).

RULE 2: Fixing Bugs

Never try to fix a bug before you have actually figured out what is causing the bug.

If you come to me and say, "My program was crashing, so I thought I would try such-and-such," then I will send you away.

If I point out a wrong piece of code and you say, "I had it right, but the program wasn't working, so I changed it," then I will send you away.

Never change correct code to something that you know is wrong or to something that you are trying because it seemed to work for someone else. You must identify the problem and know how to fix it before you change your code. If you want to try something to see how it works, then do so in a separate small program that focuses on just that feature. I mean it: I'll send you away.

Having said all this, I'll also add that it is fine to play around with a program in order to get more information about what is going wrong or to better understand the language features. But before you start playing, make sure that you have saved your original program in a separate location.

FTL Function too long.

Make your functions short, with about five to nine steps each and no more than 35 lines of code after the variable declarations. This limit includes comments and necessary blank lines.

LTL Lines too long.

Make the lines of your programs no more than 80 characters. If a long line is caused by a long boolean expression or a long arithmetic expression, then write a separate function to carry out that calculation, and call the function. For other lines that exceed the limit, choose a logical place to break the line into two or more pieces. Each piece after the first should be indented an extra four spaces. Part of the purpose of FTL and LTL is to ensure that an entire function is easily visible at one time.

FCI File comment incomplete.

Each .cxx or .h file must have a comment at the top indicating the file name, the name and email of the programmer (that's you), the date it was written, the TA's name, the recitation time, and a concise but complete description of the purpose.

II Incorrect indenting.

Note: If you use our version of emacs for Windows, then pressing the ESCAPE key followed by p will do much of this indenting for you automatically.

There are many ways people indent their C++ code, but the one way that we'll accept is described here. This way has some advantages in readability, but more than that (1) if you are all consistent it helps us read your code, and (2) in real life you'll have to get used to following specific guidelines in your code, so why not get some practice now.

The rules are:

For example...

void foo(int x, int y) 
int i;
for (i = 0; i < N; i++)
cout << i << endl;
cout << i*i << endl;
if (i > M)
cout << "M exceeded" << endl;

WS White space.

Programs are more readable if the code has meaningful white space separating parts. But not too much (don't double space the whole program). In particular, one blank line should occur: One space should occur before and after all binary operations in an expression (except for multiplication and division). This includes the input (>>), output (<<) and assignment (=) operators. Also one space after keywords for, while, if, and one space after each semi-colon in the control of a for-loop.

BN Bad name.

Choose names for functions and variables that convey what they are used for. Variables that are just used for indexing or counting in a loop should have short names such as i or n or t.

CN Capitalization and naming style.

Variable and function names are lowercase letters with an underscore to separate different words, such as plant_age. Names of constants are all upper-case letters with underscores to separate new words, such as MANY_COLUMNS.

Functions that do not return a value (void function) must have a verb as the first part of the name (such as print_table). Functions that return a bool value must have the word "is" as the first part of the name (such as is_inside). Other functions that return a value must have a descriptive noun or noun phrase as the entire name (such as feet_per_second).

GV Global variable.

These are forbidden, although global constants are allowed.

DC Define constants.

All numbers (except -1, 0, 1 and 2) and all strings that might later be changed must be declared as constants with meaningful names. No exceptions until you reach the second semester.

PCI Prototype Comment Incomplete.

Each function prototype needs a comment explaining how the function is used. Put this function immediately after the prototype. The comment must fully explain the purpose of each function parameter and the meaning of the function's return value (if there is one).

ECI Explanatory Comments Incomplete.

If there's something difficult about the code in a function definition, explain it in a comment near the difficult code. Long stretches of code should be broken into smaller pieces (around 6-10 lines per piece) with a short comment at the top of each section to explain its purpose. A programmer should be able to read these comments to get a general idea of a program's flow.

UC Unnecessary comment.

With carefully choosen names, you'll need few comments, and a programmer can read these few comments to get a general idea of the program flow (or to understand difficult parts). Comments that explain the obvious are bad; leave them out.

CTC Code too complex.

Find a simpler approach to solving the problem.

FRP Function return problem.

Use value parameters or const reference parameters to get info into functions. Whenever possible, use return to send information back to the calling program. Use non-const reference parameters only when you must. (generally, when the function produces several pieces of information). Avoid functions that return information with a return statement and also returns other information through its parameters. Avoid using an if-else statement to return a boolean value. For example, consider this code:
if (x < 0)
return true;
return false;
The preference is to omit the if-statement and just have a return statement: return (x < 0);.

BUI Bad user interface.

Clearly label all output, so the user can tell what the program has done. If user input is requested, then provide a reasonable prompt. Avoid asking the user to provide information that the program can to figure out for itself.

DNW Does not work.

This part of the code won't do what it needs to.


Will not compile.


Program must compile under the -Wall option with no compiler warnings.

PDR Poor data representation.

An example would be using separate variables to hold information that could be more easily handled in an array.

MD Misplaced declaration or definition.

All variable declarations must be together at the top of a function's definition. This makes it easier for a programmer to find the declarations.

As shown in the textbook, function prototypes should precede main() and function definitions should follow main(). These must be in alphabetical order to make them easy to find.

NMR Needs to be more robust.

For some assignments, you will be required to make the program robust. This means that if the user makes an error this part of the program could blow up or behave unpredictably. (We won't require this right away because robustness requires some advanced programming techniques.)

NGE Not general enough.

This marks a place where the program is unnecessarily limited in what it can handle. For example, if a program can handle only input names with up to ten letters, then the program is unneccessarily restrictive. Surprisingly, more general programs are often shorter and simpler, not longer and more complex, than ones which handle special cases.

CF Combine functions.

The code uses two or more different functions to do very similar jobs. This mark says that one single function with parameters would be a better approach.

PORT Portability.

Avoid using non-portable code (such as the conio.h header file). The only exception that we'll allow is the use of winbgim.h for graphics.