summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/contributing
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2022-12-22 20:04:52 +1100
committer Vas Crabb <vas@vastheman.com>2022-12-22 20:04:52 +1100
commit8edb88dbaab9efbc0b1d843656fecc4b0f087df3 (patch)
tree14aa9ed57a649807bbdcfd0860f2b900b80ac835 /docs/source/contributing
parenta88b7def11e03a7df0263842e69087546411313c (diff)
C++ guidelins update and cleanup:
docs: Expanded C++ guidelines following suggestions by P. Mackinlay. ui/inifile.cpp: Got rid of the check for "arcade" systems - it broke managing favourites for the slotted Neo Geo. luaengine.cpp: Removed the "type" property from system driver metadata. It's effectively deprecated. bus/vme/vme_fcisio.cpp, commodore/mps1230.cpp: Fixed inappropriate use of machine type flag constants. megadriv.xml: Made notes about the two Galaxy Force 2 sets more explcit.
Diffstat (limited to 'docs/source/contributing')
-rw-r--r--docs/source/contributing/cxx.rst87
1 files changed, 75 insertions, 12 deletions
diff --git a/docs/source/contributing/cxx.rst b/docs/source/contributing/cxx.rst
index 67ac6f678f8..918c72032d2 100644
--- a/docs/source/contributing/cxx.rst
+++ b/docs/source/contributing/cxx.rst
@@ -42,6 +42,23 @@ Llama case:
capitalised, with no separators between words: ``LlamaCaseSample``
+.. _contributing-cxx-fileformat:
+
+Source file format
+------------------
+
+MAME C++ source files are encoded as UTF-8 text, assuming fixed-width
+characters, with tab stops at four-space intervals. Source files should
+end with a terminating end-of-line. Any valid printable Unicode text is
+permitted in comments. Outside comments and strings, only the printable
+ASCII subset of Unicode is permitted.
+
+The ``srcclean`` tool is used to enforce file format rules before each
+release. You can build this tool and apply it to the files you modify
+before opening a pull request to avoid conflicts or surprising changes
+later.
+
+
.. _contributing-cxx-naming:
Naming conventions
@@ -84,6 +101,18 @@ Template parameters
Template parameters should use llama case (both type and value
parameters).
+Identifiers containing two consecutive underscores or starting with an
+underscore followed by an uppercase letter are always reserved and
+should not be used.
+
+Type names and other identifiers with a leading underscore should be
+avoided within the global namespace, as they are explicitly reserved
+according to the C++ standard. Additionally, identifiers suffixed with
+``_t`` should be avoided within the global namespace, as they are also
+reserved according to POSIX standards. While MAME violates this policy
+occasionally – most notably with ``device_t`` – it’s considered to be an
+unfortunate legacy decision that should be avoided in any new code.
+
.. _contributing-cxx-literals:
@@ -109,6 +138,13 @@ the intended use of a given literal at a glance. Uppercase long integer
literal suffixes should be used to avoid confusion with the digit 1,
e.g. ``7LL`` rather than ``7ll``.
+Digit grouping should be used for longer numeric literals, as it aids in
+recognising order of magnitude or bit field positions at a glance.
+Decimal literals should use groups of three digits, and hexadecimal
+literals should use groups of four digits, outside of specific
+situations where different grouping would be easier to understand, e.g.
+``4'433'619`` or ``0xfff8'1fff``.
+
Types that do not have a specifically defined size should be avoided if
they are to be registered with MAME’s save-state system, as it harms
portability. In general, this means avoiding the use of ``int`` for
@@ -450,6 +486,16 @@ a pull request.
Structural organization
-----------------------
+All C++ source files must begin with a two comments listing the
+distribution license and copyright holders in a standard format.
+Licenses are specified by their SPDX short identifier if available.
+Here is an example of the standard format:
+
+.. code-block:: C++
+
+ // license:BSD-3-Clause
+ // copyright-holders:David Haywood, Tomasz Slanina
+
Header includes should generally be grouped from most-dependent to
least-dependent, and sorted alphabetically within said groups:
@@ -491,20 +537,37 @@ follows:
#define VERBOSE (0)
#include "logmacro.h"
-The class declaration for a machine driver should be within the
-corresponding source file. In such cases, the class declaration and all
-contents of the source file, excluding the ``GAME``, ``COMP``, or
-``CONS`` macro, should be enclosed in an anonymous namespace.
+In most cases, the class declaration for a system driver should be
+within the corresponding source file along with the implementation. In
+such cases, the class declaration and all contents of the source file,
+excluding the ``GAME``, ``COMP``, or ``CONS`` macro, should be enclosed
+in an anonymous namespace (this produces better compiler diagnostics,
+allows more aggressive optimisation, reduces the chance of duplicate
+symbols, and reduces linking time).
+
+Within a class declaration, there should be one section for each member
+access level (``public``, ``protected`` and ``private``) if practical.
+This may not be possible in cases where private constants and/or types
+need to be declared before public members. Members should use the least
+public access level necessary. Overridden virtual member functions
+should generally use the same access level as the corresponding member
+function in the base class.
+
+Class member declarations should be grouped to aid understanding:
+
+* Within a member access level section, constants, types, data members,
+ instance member functions and static member functions should be
+ grouped.
+* In device classes, configuration member functions should be grouped
+ separately from live signal member functions.
+* Overridden virtual member functions should be grouped according to the
+ base classes they are inherited from.
+
+For classes with multiple overloaded constructors, constructor
+delegation should be used where possible to avoid repeated member
+initialiser lists.
Constants which are used by a device or machine driver should be in the
form of explicitly-sized enumerated values within the class declaration,
or be relegated to ``#define`` macros within the source file. This
helps avoid polluting the preprocessor.
-
-Type names and other identifiers with a leading underscore should be
-avoided within the global namespace, as they are explicitly reserved
-according to the C++ standard. Additionally, identifiers suffixed with
-``_t`` should be avoided within the global namespace, as they are also
-reserved according to POSIX standards. While MAME violates this policy
-occasionally – most notably with ``device_t`` – it’s considered to be an
-unfortunate legacy decision that should be avoided in any new code.