Hasker's SE 2040 Style Guide

In addition to correctness, solutions will be graded for style and design. Detail is given below; but the quick list is

meaningful identifiers

format code nicely with spaces around operators and no tabs

document each file as listed below

document each class, method as discussed below

minimal scope for variables

methods, classes have clear purpose

good exception processing

Use meaningful names for identifiers. One-letter names for loop variables is ok, but not method names or attributes.

Format your programs consistently and nicely, including

ensuring there are no tabs in your file (if you don't know how to fix this, ask!)
ensuring that all indentation is consistent (2 to 4 spaces for each indentation, indenting to show flow of control)

indent comments with the code:

        // capture behavior common to all birds that swim
        public abstract class Waterfowl {
           // move in pattern typical for this type of bird
           public abstract void swim();
        }

using blank lines to separate methods and separate attributes from methods
adding spaces around operators such as *, +, <, ==, &&: x * y < a, not x*y<a

one space after each comma; for example:

        public void printResults(String[] items, int first, int last,
                                 String key);

keeping lines shorter than 100 characters

Include a comment at the top of each source file you submit giving basic information:

// 
// Course:     SE 2040
// Term:       Spring 2016
// Assignment: assignment name
// Author:     your name
// Date:       date started
//

This will allow identifying misplaced files.

If numeric constants are used in multiple places (such as the maximum length of a string), create a named constant for that number and use it appropriately. For example:

        const int BUFFER_SIZE = 50;
        double toProcess[BUFFER_SIZE];

Except in rare circumstances, do not declare named constants for test code to avoid creating maintenance problems.

All variables must have minimal scope. That is, they should not have any more visibility than necessary for the design. Variables which are local to a method should be declared within it, and attributes should private or protected, Package scope can be used, but only when absolutely necessary.

Methods (aka functions) need to have a single purpose. For example, computing some result and printing it out in the same method is doing too much at once. Break such code into multiple methods/functions. Generally, no method/function should be longer than about 15 lines of code unless it has a switch statement in it, and even then the individual cases should be just a few lines long. If you can justify a longer method, then you are probably fine, but look closely for ways to break long sections of code into smaller pieces.

Likewise, classes should have a clear purpose. If a class is responsible for lots of different things, then some of those responsibilities should be given to a different class.

Do not use exceptions for normal processing. For example, it is a bad idea to use exception handling to deal with cases where data is not in a container.

If you catch an exception, deal with it in some reasonable fashion such as printing an error message and resuming processing. Never simply catch an exception and ignore it without a strong, documented reason.

When required, documentation for all classes and public methods other than getters and setters. You do not have to provide Javadoc documentation for constructors or data unless there is something notable about the element that may need to be captured for future maintenance.

Feel free to document your code in ways beyond the minimum, but make sure your documentation adds information. Comments like

        distance += 10; // add ten to distance

are worse than useless - don't write a comment if its opposite is obviously false.

Note:

.cpp

here