summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/techspecs/naming.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/techspecs/naming.rst')
-rw-r--r--docs/source/techspecs/naming.rst146
1 files changed, 146 insertions, 0 deletions
diff --git a/docs/source/techspecs/naming.rst b/docs/source/techspecs/naming.rst
new file mode 100644
index 00000000000..a973d585aba
--- /dev/null
+++ b/docs/source/techspecs/naming.rst
@@ -0,0 +1,146 @@
+MAME Naming Conventions
+=======================
+
+.. contents:: :local:
+
+
+.. _naming-intro:
+
+Introduction
+------------
+
+To promote consistency and readability in MAME source code, we have some
+naming conventions for various elements.
+
+
+.. _naming-definitions:
+
+Definitions
+-----------
+
+Snake case
+ All lowercase letters with words separated by underscores:
+ ``this_is_snake_case``
+Screaming snake case
+ All uppercase letters with words separated by underscores:
+ ``SCREAMING_SNAKE_CASE``
+Camel case:
+ Lowercase initial letter, first letter of each subsequent word
+ capitalised, with no separators between words: ``exampleCamelCase``
+Llama case:
+ Uppercase initial letter, first letter of each subsequent word
+ capitalised, with no separators between words: ``LlamaCaseSample``
+
+
+.. _naming-transliteration:
+
+Transliteration
+---------------
+
+For better or worse, the most broadly recognised script in the world is
+English Latin. Conveniently, it’s also included in almost all character
+encodings. To make MAME more globally accessible, we require Latin
+transliterations of titles and other metadata from other scripts. Do
+not use translations in metadata – translations are inherently
+subjective and error-prone. Translations may be included in comments if
+they may be helpful.
+
+If general, if an official Latin script name is known, it should be used
+in favour of a naïve transliteration. For titles containing foreign
+loanwords, the conventional Latin spelling should be used for the
+loanwords (the most obvious example of this is the use of “Mahjong” in
+Japanese titles rather than “Maajan”).
+
+Chinese
+ Where the primary audience was Mandarin-speaking, Hanyu Pinyin
+ should be used. In contexts where diacritics are not permitted
+ (e.g. when limited to ASCII), tone numbers should be omitted. When
+ tones are being indicated using diacritics, tone sandhi rules should
+ be applied. Where the primary audience was Cantonese-speaking
+ (primarily Hong Kong and Guandong), Jyutping should be used with
+ tone numbers omitted. If in doubt, use Hanyu Pinyin.
+Greek
+ Use ISO 843:1997 type 2 (TR) rules. Do not use traditional English
+ spellings for Greek names (people or places).
+Japanese
+ Modified Hepburn rules should generally be used. Use an apostrophe
+ between syllabic N and a following vowel (including iotised vowels).
+ Do not use hyphens to transliterate prolonged vowels.
+Korean
+ Use Revised Romanisation of Korean (RR) rules with traditional
+ English spelling for Korean surnames. Do not use ALA-LC rules for
+ word division and use of hyphens.
+Vietnamese
+ When diacritics can’t be used, omit the tones and replace the vowels
+ with single English vowels – do not use VIQR or TELEX conventions
+ (“an chuot nuong” rather than “a(n chuo^.t nu*o*'ng” or “awn chuootj
+ nuowngs”).
+
+
+.. _naming-titles:
+
+Titles and descriptions
+-----------------------
+
+Try to reproduce the original title faithfully where possible. Try to
+preserve the case convention used by the manufacturer/publisher. If no
+official English Latin title is known, use a standard transliteration.
+For software list entries where a transliteration is used for the
+``description`` element, put the title in an ``info`` element with a
+``name="alt_title"`` attribute.
+
+For software items that have multiple titles (for example different
+regional titles with the same installation media), use the most most
+widespread English Latin title for the ``description`` element, and put
+the other titles in ``info`` elements with ``name="alt_title"``
+attributes.
+
+If disambiguation is needed, try to be descriptive as possible. For
+example, use the manufacturer’s version number, regional licensee’s
+name, or terse description of hardware differences in preference to
+arbitrary set numbers. Surround the disambiguation text with
+parentheses, preserve original case for names and version text, but
+use lowercase for anything else besides proper nouns.
+
+
+.. _naming-cplusplus:
+
+C++ naming conventions
+----------------------
+
+Preprocessor macros
+ Macro names should use screaming snake case. Macros are always
+ global and name conflicts can cause confusing errors – think
+ carefully about what macros really need to be in headers and name
+ them carefully.
+Include guards
+ Include guard macros should begin with ``MAME_``, and end with a
+ capitalised version of the file name, withe separators replaced by
+ underscores.
+Constants
+ Constants should use screaming snake case, whether they are constant
+ globals, constant data members, enumerators or preprocessor
+ constants.
+Functions
+ Free functions names should use snake case. (There are some utility
+ function that were previously implemented as preprocessor macros
+ that still use screaming snake case.)
+Classes
+ Class names should use snake case. Abstract class names should end
+ in ``_base``. Public member functions (including static member
+ functions) should use snake case.
+Device classes
+ Concrete driver ``driver_device`` implementation names
+ conventionally end in ``_state``, while other concrete device class
+ names end in ``_device``. Concrete ``device_interface`` names
+ conventionally begin with ``device_`` and end with ``_interface``.
+Device types
+ Device types should use screaming snake case. Remember that device
+ types are names in the global namespace, so choose explicit,
+ unambiguous names.
+Enumerations
+ The enumeration name should use snake case. The enumerators should
+ use screaming snake case.
+Template parameters
+ Template parameters should use llama case (both type and value
+ parameters).