Coding Standards

Beyond the functionality required by each assignment, your code will be assessed on how well it is written and engineered.

Click here to download a PDF of the rubric that graders will follow as they do that assessment.

We expect most submissions will receive a score of 0 in each of the four categories. Scores of 1 should be regarded as exceptional, not the norm. Scores of -1 indicate that you should meet with your grader and confer about how to better meet the coding standards expected in this course.

Grades

Coding standards are a separate component of your course grade. To determine that component, we will drop your lowest two scores in each category, calculate your resulting average score in each category, and take a weighted average of the four scores (30% for each category except 10% for Formatting). That weighted score is between -1 and 1 and will be mapped into a percentage as follows:

• [-1, 0]: mapped to [0%, 80%]
• [0, 1]: mapped to [80%, 100%]

So consistently failing to meet standards will have a substantial negative impact on your grade, occasional lapses will not, and expending a great deal of effort on exceeding expectations will be rewarded by a small amount.

Coding Style

Style is included in the coding standards rubric as part of the Comprehensibility category. We used to maintain a 3110 style guide, but that is now deprecated. Instead, we refer you to the guidelines for source code that have been developed by the OCaml community.

Editor

Your editor can be a powerful ally in improving your source code. We recommend that you configure your editor to do the following:

• automatically indent your code using ocp-indent
• alert you whenever your source code goes over 80 columns

The VS Code editor on the VM has already been configured that way for you.

Imperative Features

Functional programming is awesome, or so we believe, and in the beginning we’re going to ask you to quit “cold turkey” on imperative programming. That means not using any of OCaml’s imperative features. Here is the short list of prohibited features:

• The built-in imperative data types: refs, arrays, and mutable fields.
• The Buffer, Bytes, Hashtbl, Queue, and Stack modules.
• The deprecated functions in the String module.

If you do use any of those features, your submission will receive a substantial penalty. The amount will depend on the degree of your violation, but could be around 50% on the entire assignment (not just the coding standards). We happily will reduce the penalty to be quite small if you then submit a revised assignment that eliminates use of the prohibited features.

About halfway through the semester, we will flip the switch and allow all those features.

On the other hand, these features are always explicitly permitted:

• Input and output, to the console or to files, is permitted even though it has side effects.
• Loops are not inherently imperative hence are permitted. But most of the time they are useless in the absence of other imperative features.

If you have questions about whether any other features should be on either of these lists, please ask.