Haskell style guide

Introduction

The following style rules will be strictly enforced when grading homeworks...

Required Elements

TP

Every top-level function declaration must be accompanied by an explicit type declaration. For example, write

myfunc :: Integer -> Integer -> [Integer] -> [Integer]
myfunc x y z = (x+y) : z
instead of just:
myfunc x y z = (x+y) : z
These declarations will sometimes be fairly obvious (from the function definition itself, its name, nearby comments, or whatever), but getting into the habit of writing them all the time is good discipline.
TS

Every significant piece of functionality must be accompanied by testing code demonstrating that it works. In particular, every solution to a homework exercise must include a "test driver" that shows how it behaves on several examples.

Naming

N

Use meaningful names. Choose names that reflect the intended use of the value referred to by the name. Names are documentation.

As a general rule, short names (one or a few characters) are appropriate for variables with small scopes, like parameters to functions, while longer names are appropriate for more global definitions, such as top-level functions.

NF

Follow standard Haskell conventions for choosing names.

When forming long names from multiple words, smash the words into a long string and capitalize the first letters of the second and following words-- e.g., veryLongFunctionName (rather than very_long_function_name or anything else).

When pattern matching against a list, if you call the head foo, then use foos for the tail.

Comments

C

Use comments to make your code easier to read. Most top-level declarations are improved by a short comment. However...

OC

Do not over-comment. Very many or very long comments (especially within the body of a function) are more distracting than helpful.  Long comments may appear at the top of a file or section of code if you need to explain the overall design of the code or refer to any sources that have more information about the algorithms or data structures.  All other comments in the file should be as short as possible.  A good place for a comment is just before a function declaration.  Judicious choice of variable names can help minimize the need for comments.

Avoid comments that merely repeat the code they reference or state the obvious:

-- This function increments its argument 
inc :: Integer -> Integer 
inc x = x+1

E Use proper English. Comments need not always be written in complete sentences, but when they are, standard rules of English grammar apply. Spelling also counts.

Miscellaneous

IN

Use consistent indentation. There are several reasonable styles for indenting code in Haskell. Choose one and stick with it.

80

80-column lines. No line in your program should be longer than 80 characters.

Although most screens are wide enough now to display much longer lines, there are still many editors whose default width is 80 characters, and 80 character lines are the natural width for printing programs in reasonable-sized fonts.

Submission

MC

Submitted code must compile. Any code you submit must be accepted by GHC without errors or warnings. Never submit anything that you have changed, no matter how small the change, without checking it with GHC. If you want to include code that doesn't work (e.g., for partial credit), put it in a comment.

Code for which GHC generates warnings or errors will not be graded.

HD

Include a header comment giving at least your name, the date, and the number of the assignment.