MeanField_SERiF/EmilysRulesForSERiFCode.md

Emily's Rules for writing good SERiF code

If you will bear with me as I indulge in some prose. Astronomers are, as a rule, bad at programming. We are a discipline focused on the abstract, though not that abstraction that is code. There are many effects this has had on astrophysical code, though I would argue that the primary effect is a paucity of good code. Do not misunderstand me reader, I do think there is good astrophysical code that exists; it is only that I think that more good code should exist, that more good code could exist.

There is perhaps an inescapable degree of egotism inherent in acting as the initial and lead developer for a code such as this. I have, by necessity, had to impose my own views on what makes a software product pleasant to develop for and pleasant to use. These are likely wrong, in so far as any views can be wrong. I think it likely that no one is 'correct' in these things. Rather, what is important is that there be some views. Yes you could, I'm sure, poke holes in any one of the points below. However, these points have been more or less agreed upon for this code base and therefor should be followed, for consistency if not for correctness.

• Always remember the users of the code are astronomers not developers. All user facing code must be understandable by a senior undergraduate physics major.
• We are writing physics, user facing code should always prefer to describe physical intent.
• Other concerns (e.g. memory, numerics, IO, etc...) may be accessible through options; however, those options names should make it clear to users that they are straying into dangerous water
• The hierarchy of abstraction is physics > numerics > IO > memory. A user should need to put more effort into adjusting numerics than physics, and more effort into adjusting IO and memory than numerics.
• Here we write a library not an application. Do not concern yourself with such petty things as an entry point, command line arguments, etc... Rather, we provide tools for others to build applications with.
• The tools we provide should allow a user to construct a stellar model in less than 20 lines of code.
• Those same tools should also provide options which allow an advanced user to take near full control over their numerics and physics.
• Code should be self documenting, vowels don't bite. Leave them in your names.
• Developers are also astronomers, code should therefore not try to be too clever with syntax tricks.
• At the same time languages are advanced and complex, do not prevent yourself from writing code just because it is may be hard to understand. If you think that your way is best then it likely is. Just make sure you explain why you are doing what you are doing in a comment.
• Write comments that explain why not what
• All functions must have a docstring.
• Prefer compile time verification over runtime verification.
• Compile time invariants should be exercised with static_asserts in the compile_time_checks static library. A failing invariant should prevent the code from compiling
• Use the minimum header set you can
• Do not use exceptions for normal control flow.
• The library can throw exceptions; however, generally only the user should catch them.
• Within the library error states should be reported as a value (std::optional, std::expected, etc...)
• When an exception is thrown make it detailed. It should include what went wrong, where it went wrong, why it is wrong, if applicable what was received instead, and what the user can do to fix it.
• Prefer more and smaller files over fewer and larger files.
• Prefer more and smaller classes over fewer and larger classes.
• Prefer more and smaller functions over fewer and larger functions.
• Do not include the full mfem.hpp header. Its slow, I will send you an angry email.
• AI is a tool, its okay to use it, but use it as a tool not as a crutch. You must understand all the code you write.
• The less something is related to physics the more you may consider AI. A build system configuration for example is a good candidate for AI. A physics function is not.