Style Guidelines
================

As a preface: I break these guidelines occasionally. It is
important to note that I often find myself up into the
early morning hours (sometimes even as early as 03:00)
developing Keraforge. Late-night coding sessions tend to
lead to mistakes that I accidentally push to prod. Feel
free to point these mistakes out to me!

Zen
---

1. Keep types simple.
   - If your type is complex enough to be unreadable, maybe
   you should change your type.
   - Function pointers may be disgraceful to write, but if
   you write your code in such a way that avoids writing
   the type more than once then you'll be fine.
   - See: `struct kf_actorregistry`. I use some quirky
   types there, but nothing too unreadable. Notice how I
   never rewrite those types again and notice that I am not
   using a typedef either.
   - Additionally, if the user is never going to use that
   type then it almost definitely does not need to be
   typedef'd.
2. Documentation is important.
   - "Self-documenting code" is not sufficient. If the item
   is public then it should have an explanation.
   - The ONLY exceptions to this rule are blatantly obvious
   struct fields, such as `position`, `velocity`, etc.
   - A few lines of documentation will save you a massive
   headache in the future.
3. Macro magic is garbage, but unmaintainable code is worse.
   - Using macro magic sparingly can help prevent you from
   being smitten by the DRY deities. Save yourself today!
   - See: math.h, log.h, and bini.h for cases where macro
   magic is acceptable.
4. Keep names terse but readable.
   - I don't want to see stdlib-style function names, but I
   would much rather that over a name ripped from an
   object-oriented C.
   - If you must use a stdlib-style function name to remain
   terse, then please provide a sentence in its docs to
   explain the name.
5. Most importantly: Be simple.
   - This often means sitting at your screen pondering the
   best implementation for something rather than simply
   using the first one that comes to mind.
   - It's okay to sacrifice a bit of performance for more
   maintainable code.
   - If you must write complex code, please explain why via
   a brief comment.

Basics
------

See <etc/style.c> for a sample of the style with comments
explaining each main point.

For more specifics, please give a skim throughout the
codebase itself.

- Prefer [iuf](8|16|32|64) over (float|double|(u?int(8|16|32|64)_t)).
- Do not typedef function pointers (see Zen #1), structs, enums, or unions.
- Use global variables instead of requiring the user to maintain state.
  See: kf_uiconfig, kf_actors, kf_actorregistry, kf_state, etc.
- Use `struct kf_vec2(type)` instead of `struct kf_vec2f32`.
- Do not modify libraries included in the source.
  Those are: bini.h.
- I'm not afraid to postfix _t to typedef'd types. The standard is useless here since we prefix kf_ anyway.
  (I think this standard is useless *to begin with*, but I digress)