add developer documentation and design principles

[s9105947]

New section "Developer Documentation" is aimed at developers wanting to work on PICMI itself. Its content may be of interest to implementors, but should not be required knowledge to them.

The design principles outlines fundamental design decisions and aims to clarify misunderstandings on PICMI at an early stage.

---

Key points that are important to me personally:

• Users are not allowed to access attributes directly.
• Implementing codes use the same attributes as the users, but may be offered additional representations of the same data (e.g. laser E0/a0)
• Implementing codes receive a integrity guarantee from the check interface.

[s9105947]

Note: I am not that familiar with the rst format, feel free to make suggestions.

[s9105947]

I've proofread and would put considers this document "done", at least for the basics.

I summon @dpgrote @ax3l @BrianMarre for their opinions!

[ax3l]

Users are not allowed to access attributes directly.

I have no problem with that point. The only thing we should note is that writing attributes directly can invoke undefined behavior (inconsistent objects if not all corresponding members are updated). Reading is actually no issue, unless we want to hide unit conversions within.

[ax3l]

@s9105947 @BrianMarre just a minor question to clarify above, if you have a chance :)

[BrianMarre]

Yes it probably is a good idea to note that writing to attributes causes undefined behaviour, and yes I agree that reading should not cause problems, as in both will probably not cause and should under no circumstances cause problems by design.

Edit: I did change my mind somewhat, we should discourage the user from needlessly reading variables but it should not be disallowed in general