Title: Coding Standards

Used by both Marlinspike and Demeter code.

Topic: Case and Naming Conventions

ALL_CAPS: 
* Constants

CapitalizedCamel:
* Classes
* Unique system objects
* Global routines
* Global arrays/tables
* Verbs

lowercaseCamel:
* variables (whether global, local, instance, or parameters)
* instance variables (fields, properties; always preceded by relevant _obj._)
* methods() (embedded routines)

Capitalized_With_Underscore:
* Locations 
* NPCs 

Titlecase_with_Underscore:
* Scenes

lowercase_with_underscore:
* Props
* (some Inform globals)


Topic: Documenting Practices

* !! is a documentation-level comment, to be extracted into a document like this
* ! is an implementation-level comment, meant for readers of the code itself
* Method and routine parameters listed in documentation with an appended * are optional parameters.
* Class design decisions forced by the constraints of Inform should be documented in a sectioned named "Inform Implementation".


Topic: Coding Practices

* Pre-processor-like directives meant for the compiler should be preceded by #.

* Generally, objects in the story world use underscore_names while most system objects use camelNames.  (That's the goal, anyway.  Inform's standard library doesn't always seem to be consistent in naming things either, so it can still seem like a mish-mash at times...)

* Globals (whether constants, routines, or variables) that are logically associated with a class should be preceded with the class name and then two underscores.  Examples: Classname__MY_CONSTANT, Classname__GlobalRoutine().


Topic: Files

* Most Marlinspike files use the .h extension, since they are intended to be included into another .inf file that contains the start of the program.  Such .h files should surround their contents with include guards, as in:
>
> #Ifndef FILE_NAME_H;
> #Constant FILE_NAME_H;
> ! ... contents of file here ...
> #Endif; !FILE_NAME_H
>

* Most Marlinspike files contain a single class (plus any associated routines, globals, constants, etc), and so should have the same name as the class, using CapitalizedCamelCase.  Additionally, they usually include the _#System_file_ directive. This means they don't produce compile-time warnings (such as for routines that are defined but not used), and their routines can be replaced by using _Replace_.  (The _#System_file_ directive should actually go before the include guard, since that way it will suppress the warning about the include guard constant never being used.)

* Marlinspike filenames that are all lowercase are usually files that include other files, though some specify multiple small related objects or classes. 

* Include files generally have the same name as the directory/package and include an overview of that package.  Simply include this single file and you will include all class files defined in that package.

* Documentation files are given in lowercase_with_underscores.txt files.  (Note the .txt extension.)

* When a file contains a class (as most do), the file should begin with a general description of the class (even though the actual class definition in code does not start until after the Globals are defined).  Then specific details should be documented (using the "Group" keyword) in the following order: Constants, Globals (variables, then routines), Extends, Instance Variables (public only), Class Methods, Methods.  Within a group, items should be defined alphabetically (though this is a pretty loose rule: it really only applies to methods or any group with 4 or more items.)  Finally, if a class defines related game verbs or includes unique objects as integral components, those should be defined in a later "Section".


Topic: Classes

* Inform has no package or namespace mechanism, and uses a lot of global variables and such.  Therefore, to avoid name conflicts, all Marlinspike class names are preceded by the letter M.  Yes, this is rather ugly.  And the question of pronunciation is still pending: do you say the M?  This actually matters for documentation--whether to use _a_ or _an_ as an article when referring to an instance of the class.  Generally, it's preferred to ignore the M as much as possible--pretend it's not there unless saying it is necessary to distinguish it from another class of the same name.  When saying the M, it's a separate letter: _MObject_ is an "em-object", rather than a "mobject".  (Compare this to a <MWObject>.)

* It is recommended that an implementing class follow the same rule and apply a single letter to all its own class names.  (Demeter uses a _D_)

* Demeter also prepends a second letter after the D for certain unique objects: DA for actions, DS for scenes, DR for reactions, and DT for triggers.  DV is used for verb constants (which are actually just strings).  All these caps in a row make the name hard to read, so these prefixes are followed by an underscore (_) before the actual class or object name.


Topic: Methods

* Method names should always start with a verb.  [Exceptions: _size()_]

* Parameters should be listed on the same line as the method (or routine) name, after the opening [.  Local variables should be listed on the next line.  Preferably, there should be a space between the method name and the [.

* Accessed instance variables should _always_ be preceded by the appropriate _obj._, which is often _self._.  (Failing to do so in Inform can generate warnings or, occasionally and more detrimentally, quiet errors.)


Topic: Object Names

* Some object--notably, actions, scenes, and verbs--should include a more printable "name" than their variable name.  This name can include spaces.  Action names should be all uppercase (_ACTION_).  Verb names should be capitalized (_Verb_).


Section: Class Diagrams

Each package provides an overview of the hierarchy of classes and unique objects defined in that package.  These overviews are produced using Graphviz from the .dot files found in each package.  The following representational conventions are used in these diagrams.

box, black - regular class (instances may be defined, but not at runtime)
box, black filled lightgrey - regular class with instances that can be created at runtime (with Inform limits on the number of instances) 
box, rounded slategrey - abstract class (this class should first be extended by another class before instances are made)
box, rounded black - possibly abstract class (depending on the implementing game)
ellipse, black filled gray - unique object
dashed - a relevant class or object from a different package
