Style Guide

Coding style refers to how you name your objects and functions, how you comment your code, how you use spacing throughout your code, etc. If your coding style is consistent, your code is easier to read and easier to debug as a result. Many companies enforce a specific coding style, and you won’t be able to push your code to the code base if your code does not pass the style check.

This style guide is a list of dos and don’ts for the programs you develop for the course.

CSc 345: Style Guide

External Documentation

“External” Documentation: In programming classes, the comprehensive set of documents that detail the design, development, and structure of a program are usually condensed into a comparatively brief ‘block comment’ at the top of the source code. This “external” documentation will minimally include:

  1. Your name, the course name/#, assignment name/number, instructor and TA names, and due date.

  2. Detailed description (in your own words) of the problem the program was written to solve, including the techniques (e.g., algorithms, data structures) used to solve the problem.

  3. The program’s operational requirements: Which programming language and version you used, special compilation information, where the input is located on disk, etc.

  4. Required features of the assignment that you were not able to include, and/or information about bugs that are still known to exist. (Be honest and complete!)

Class Documentation

Class Documentation: When you write a support class (e.g., one not containing the application’s main() method), it will be preceded by a block comment minimally containing the following:

  1. The name of the class, your name, the names of any external packages upon which your class depends, the name of the package of classes containing this class (if any), and inheritance information.

  2. An explanation of purpose of the class.

  3. Names and brief descriptions of any public class constants and variables.

  4. Names and brief descriptions of constructors, plus a list of the implemented class and instance methods.

Internal Documentation

The details of the program are explained by comments placed within the code. Your internal documentation will minimally include the following:

  1. A ‘block comment’ will be placed at the head of every method (a.k.a. function or subprogram). This will include the method name; the purpose of the method; the method’s pre– and post–conditions; the method’s return value (if any); and a list of all parameters, including direction of information transfer (into this method, out from the method back to the calling method, or both), and their purposes. Exception: A single block comment may cover all of the getter and setter methods of a class.

  2. Meaningful identifier names. In a nod to tradition, simple loop variables may have single letter variable names, but all others will be meaningful. Never use non-standard abbreviations. If your language has accepted naming conventions, learn and follow them.

  3. Each variable and constant must have a brief comment next to its declaration that explains its purpose. This applies to all variables, as well as to fields of structure declarations.

  4. Complex sections of code and any other parts of the program that need some explanation will have comments just ahead of them or embedded in them.

Miscellaneous Requirements

  1. Write programs with appropriate modularity; that is, create classes when appropriate, write methods that accomplish limited, well-defined tasks, etc.

  2. Public (a.k.a. ‘global’) class and instance variables will never be used in your programs for my classes unless I have approved their use for your particular situation. Use getter/setter methods instead.

  3. Be generous with your use of “white space” (blank lines) to set off logically related sections of code.

  4. Indent bodies of methods, loops and IF statements, and do so with a single, consistent style.

  5. Unconditional branching (e.g., goto statements) may not be used in your programs w/o permission.

In general, if you have a choice between writing code that runs quickly and writing code that is easy to understand, make it easy to understand. Don’t sacrifice clarity for efficiency.

Reference

This guide is derived from Dr. Lester McCann’s CSc 345 style guide.