CPSC220: Introduction to Computer Architecture (Fall 2013)

Formatting Expectation for Source Code

Formatting

Your code should be formatted to maximize readability. The basic principle to follow is that logical blocks should be clearly identifiable and viewable on the screen, without scrolling, with clear visual separation from other logical blocks.

Comments

Comments - a.k.a. "internal documentation" - are an essential component of programming, even though they are not themselves executable, providing readers (including the programmer) with information necessary to understand a program. The general idea is to add a comment for each logical section of a program.

Your programs must include the following 3 kinds of comments:

  1. File header comment. Every source code file must begin with a multiline comment of the following form:

    /*
    **  name of the file
    **
    **  Author:  your name
    **  internal title (e.g.  "CPSC 220, Assignment 1")
    **
    **  Summary: (Fill in description of your program's use and behavior here)
    **  
    **  Last modified:  the date of most recent modification
    */
    

    You are free to do more attractive ASCII art, so long as you keep the required information.

  2. Comments that document the main logical steps. Such comments should summarize what we know about the values of variables so far, and what the current logical step will accomplish. They should be no more than 2 or 3 lines (the fewer the better). In some cases, you can get away with only a trailing comment at the end of a single line.

Naming conventions (for variables, methods, classes, and packages)

Elegance

A good computer program is not only functional, but beautiful in its design. To borrow from Salieri, "Remove even one line, add even a single expression, and the whole edifice would tumble." Less dramatically, you should strive for programs that contain exactly the statements needed to produce a correct program, with source code that is easy for others to read, maintain, and perhaps expand.

This is the most subjective requirement, but there are a few hard and fast rules: