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]

Please excuse the delay.

This looks great to me. Tiny formatting inline.

@dpgrote @RemiLehe can we merge this?

[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.

[dpgrote]

This looks good to me.

[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

[BrianMarre]

I think that not encouraging read access, is justified, since read-to-set-other-variable creates a lot of implicit dependencies difficult to oversee

[ax3l]

agreed, we can recommend using getters instead

[ax3l]

@BrianMarre @s9105947 want to update accordingly? :)

[BrianMarre]

Yes, but I am on vacation right now and Hannes moved on.
I am actually not sure wether I even have write access to this pull request.
Might be that we have to get a developer to push to this pull request or, create a new one.