Document design principles

[ftomassetti]

One important principle is the pragmatic approach: our goal is not to replicate the exact some behavior of the RPG compiler running on the mainframe. It would be extremely hard to support the exact way that mathematical operation behave or to replicate exactly the way data is stored in memory. We are not aiming to doing that. We aim instead to get equivalent behavior for all reasonably common usage patterns.

For example, if somewhere there is a program performing tricks with packed numerical data and the overlay directive, then it should not be expected to work. Ideally an error or a warning should be triggered by the compiler.

This and other principles should be documented in the project and we should add examples and explanations as we take more design decisions.