Suggested Workflow

Efficiency is crucial when you’re coding. To have readable, manageable and stable code you need to have a number of habits that enable you to quickly spot and track bugs, share code with others and deliver a working output. We give hereby a simple workflow that might give you a first glimpse into how to organise your work. These habits can help you avoid standard issues related to writing no maintanable code, too cumbersome to debug or read.

How is your repository organised?

Your repository in its initial state contains:

  • Configuration files dune-project and dune that specifies how and in which order your source .ml files are going to be compiled for you to generate project executables.

  • A list of source files in the different subfolders of Source, these are the .ml files at the core of your work.

  • A list of .mli files that are called interface files, they specify and possibly restrict the type of functions defined in the corresponding .ml files. You should always have a look at them and avoid modifying them unless instructed to do otherwise.

  • A list of tests subfolders containing unit tests for the different functions in the parent folder.

How to work?

As a first approach, coding activities are summed by

  • editing source files

  • testing edited functions

  • testing of context and buildability of project

  • Saving buildable state

  • building project

Editing source files is what you’re mostly accustomed to ; you write down code you expect to follow defined specifications. This implies you using your preferred IDE. For our purposes Emacs in tuareg-mode is easily set-up and avaiable for you, you can still use anything else as long as you’re efficient and comfortable with it.

To test small edited functions while you’re writing your code, rather than executing the whole test suite made available for you, you’re advised to make local unit tests in the ocaml top-level with emacs or utop. The test suite as a whole is heavy to launch and would need a rather expert eye to analyse what went through and what didn’t. You’re given details on how to use ocaml top-level environment for micro-testing at Compiling and Testing Your Code. If you’re out of ideas for what to test you can look into the test files within the tests folders, you have there (input, output) couples for tested functions.

Testing context and buildability of project is about executing the whole testing suite. This makes it possible to test whether you didn’t destroy anything you’ve previously coded and interconnexion between your different source files.

To save buildable state, do the usual procedure, the same one as in your programming sessions. Never do it when your code is not buildable. Your code must compile and execute your local testsuites with no crash or timeout.