Various cleanup

This fixes @rizar's comment on the developer guidelines, as well as some documentation and formatting fixes to Jan's PR.
@rizar I figured that the "don't override function arguments" guideline could actually be seen as part of a broader issue where you don't want the same variable name to be used for different things within the same scope. Does this cover it you think?