Coding Standards
Beyond the functionality required by each assignment, your code will be assessed on how well it is written and engineered. There are two main categories that we will assess: testing and code quality. We put substantial emphasis on these in 3110; depending on your background, that might be new to you.
-
When it comes to testing, we will provide a handful of example unit tests for each assignment, and you will be responsible for elaborating those into a comprehensive test suite.
-
Code quality is an assessment of how easy it is for a human to understand your code. Other names for this property could include readability, comprehensibility, and style. Code quality includes the OCaml source code you write, as well as the English comments you write as documentation in the code—especially the specification comments for functions, types, and modules.
Each assignment will provide specific prompts for testing and code quality, but here are some overall concerns you should keep in mind:
-
Every required function (that is exposed through an interface) should have multiple unit tests demonstrating its correct operation.
-
It’s okay for your code not to pass every one of your own unit tests (e.g., you didn’t manage to finish implementing some function but you did write tests for it), but your code must still compile against your own test suite.
-
The OCaml Programming Guidelines is a community-maintained “set of reasonable guidelines for formatting OCaml programs—guidelines which reflect the consensus among veteran OCaml programmers.” We do our best to adhere to these guidelines in the code that we write for this course, and we expect you to do the same.
-
In OCaml code, two of our highest priority concerns are density and naming. Readable code should not be dense: not too many symbols on a line, not too many levels of nesting, not too many lines in a function, etc. Names should be self-documenting, follow consistent conventions, and not be kludgy or verbose.
-
Your editor can be a powerful ally in improving your code quality. We recommend that you configure your editor to automatically indent your code using
ocp-indent
, and to alert you whenever your source code goes over 80 columns. (The VS Code editor on the 3110 VM has already been configured that way for you.) -
In documentation, every top-level function in a module (even helper functions) should at least have a sentence describing its output in terms of its inputs. See the OCaml standard library documentation for examples.