Contributing

Project Structure

libmatoya is set up in a tree-like fashion where code in common with all platforms is at the root of /src. From there, as you go further up the tree towards the leaves, the code becomes more platform specific. A major development goal is to move as much code as possible towards the root and maintain as little as possible towards the leaves. libmatoya will never #ifdef based on platform, instead it uses the makefile to choose different paths through the tree.

• /src/windows
• /src/unix
  • /src/unix/web
  • /src/unix/apple
    • /src/unix/apple/macosx
    • /src/unix/apple/iphoneos
  • /src/unix/linux
    • /src/unix/linux/x11
    • /src/unix/linux/android

Principals

• There are two types of functions: utility and method. method functions essentially mimic the semantics of a class in an object oriented language:
  • There is always a constructor called MTY_ObjectCreate that returns a pointer to the new object.
  • There is always a destructor called MTY_ObjectDestroy that takes the object by reference, disposes of everything it can associated with the object, calls MTY_Free on the object itself, and sets it to NULL.
  • Methods appear as MTY_ObjectXXX, the method name in this case being XXX. Methods take the object as their first argument labeled ctx.

Module and Function Ordering

• Modules in matoya.h are ordered first by dependence, second alphabetically.
• method functions are always grouped together, with the constructor and destructor appearing first in the group.
• There is no strict function ordering rule beyond this, however functions that will likely be called together or should be called in succession should be ordered as such.
• Public function implementations should be ordered in the same order they appear in the header, and with the same parameter names. There is no rule for static or private symbols.

Naming

• Function naming convention: MTY_[Object|Module]VerbNoun
  • If a method function, the object name always comes first.
  • Although rare, functions may be namespaced by their module name to differentiate between other libmatoya names, i.e. MTY_CryptoHash.
  • Nouns are optional if the verb and function signature is clear enough.
  • Exception: Conversion functions in the form of MTY_XToY
  • Exception: Canonical algorithms or C standard library functions, such as MTY_CRC32 or MTY_SprintfD
  • Exception: Because "Exists" checks are common, shorthand MTY_XExists rather than MTY_DoesXExist.
• Enumeration naming convention: MTY_Noun
  • Each value in the enum should be named in accordance with the type name, i.e. MTY_ColorFormat would have values MTY_COLOR_FORMAT_BGRA and MTY_COLOR_FORMAT_NV12.
  • In the case of generic qualifiers, like the words Type, Mode, and State, that word can optionally be dropped from the value names if they don't lose clarity, i.e. MTY_EventType with values MTY_EVENT_KEY and MTY_EVENT_BUTTON.