Code Formatting Standards and Guidelines

All organizations and companies have specific conventions for formatting code. While these formatting rules may vary from place to place, they are essential for making your code readable and for enabling others to understand, use, and modify your code in the future.

Here is a longer style guide, but I prefer 2 spaces instead of the 4 advocated there.

Naming Conventions


The most-readable programs are written with prudent use of whitespace (including both blank lines and spaces).

length :: [a] -> Int
length _      = 0
length (_:xs) = 1 + length xs

File header comments

Every source code file should contain a header comment that describes the contents of the file and other pertinent information. It must include the following information:

For example:

 | Assignment 4
 | Name:    Barbara Smith
 | E-mail:
 | The main driver program for project 4.
 | This program reads the file specified as the first command line
 | argument, counts the number of words, spaces, and characters and
 | displays the results in the format specified in the project description.

Function comments

All functions must be commented. Include descriptions of the parameters (perhaps by commenting the parameter types) and what the function does. For example:

-- Inserts the xs between every element of xss and concatenates the result.
intercalate :: [a]   -- xs
            -> [[a]] -- xss
            -> [a]

In-Line Comments

You should strive for your code to be self-explanatory. However, it is inevitable that some lines of code are more intricate. In these cases, a comment describing the code is well-advised. The comment should not simply translate the code to English, but should explain what’s really going on.