Spring Cleaning

[ssoelvsten]

A clean and consistent code base that does not break (its own and general programming) conventions has several benefits:

• It increases the trust we can put into it in being correct.
• It speeds up research and student projects, since (1) getting to know the code base takes less effort, (2) implementing new features requires touching fewer pieces of code, and (3) bugs will be fewer and easier to solve.

The true and tested mantra of "slow is steady, steady is fast" applies.

Compiler

GCC Warnings

Usually, the Troupe compiler is not built with all warnings. By building it with the command below, one can generate all compiler warnings. Going through these one-by-one, we can remove dead code, missing type annotations, variable shadowing, and much more.

stack build --ghc-options -Wall

Code Quality

With #72 , we add consistent code formatting to the compiler. Yet, there are other inconsistencies such as x2Y versus xToY.

Folder Structure

• Move the list of Builtins out of compiler/src/IR.hs.
• The current compiler (compiler/src/) has a flat folder structure with no way to gauge which files do what. Instead, we should be move each phase's definition (AST) and analysis/optimisations into a subfolder; doing so, we can also split up each giant file into several to separate concerns. This mainly leaves the translation from one phase to another at the compiler/src level.
• The definition for the end-to-end in tests/ is in the compiler/test. This is undocumented, is hard to find, and violates separation of concerns. Move this part of the testing suite into tests/golden.
• compiler/test ⇒ compiler/tests for consistency with ./tests
• compiler/ ⇒ troupec/ for the folder name to correspond to the executable?

Runtime

ESLint

With #81 , we add ESLint. This highlights tons of issues that need to be fixed.

Folder Structure

• Currently, rt/src is a flat hierarchy. The different data types, e.g., list and records should be moved into a subfolder.
• Currently, the runtime is actually two folders at the root level, rt/ and trp-rt/. This is undocumented, not intuitive, and not even folders that are right next to each other. Instead, it would be easier to understand if everything is centralised in the rt folder
  • rt/src/ ⇒ rt/ts (rename)
  • trp-rt/ ⇒ rt/trp (move)
• rt/ ⇒ runtime/ to make it easier to identify this folder. This also makes it consistent with compiler/ (if not renamed).

Modularity and Type Safety

Currently, the runtime is burdened by high coupling, lacks typing guarantees, and no documentation.

• Spell out the type (.d.ts file) of objects produced by the compiler; this both encompasses the entire programs stored on disk and the functions deserialized at runtime.
• Spell out the responsibilities of each part of the the runtime and their type (.d.ts files).
• Decrease the coupling between modules. There are multiple things one can do to this end
  • In some cases, coupling is merely due to not following the contract of another module (i.e. typecasting to any and then accessing a private variable). Such easy fixes can be identified by merely specifying/documenting each module.
  • Quite a few variables are marked as private with a __ prefix but made public and accessed everywhere. The access to these variables should be granted in some other way.
  • Currently, everything (including singletons) is parsed around by pointer. As such, this makes sense to emulate the idea of capabilities; a part of the runtime can only touch something if given the pointer (permission) to do so. But in practice, this results in constructors with tons of arguments, everything being parsed around to everyone (meaning everyone has access anyway), and inconsistent access to the same object. The singleton pattern seems the less of two evils.

Documentation

• Consider moving the Installation section out of README.md and into the documentation (formerly known as the User Guide).
• Generate the Builtins section of the documentation from compiler/src/IR.hs or some other centralized source of truth.
• Generate the Standard Library section of the documentation directly from the lib/ folder.

Other

• The folder test-relay/ folder should be moved somewhere else. Furthermore, it is a testing artifact, not something to be committed. After moving to a more sensible place, it should also be generated as part of the testing script and then be ignored by git.