Document macro naming style and struct naming style in C-compatible code, where C++ namespaces can't be used to avoid name collisions. No bug, r=luke over IRC, DONTBUILD because this is modifying docs but touching no code
authorJeff Walden <jwalden@mit.edu>
Wed, 28 Mar 2012 15:42:40 -0700
changeset 90575 732633ac1e07036c6e3dce6eceba4dac9210c76a
parent 90574 5f280b4ff6f840d28ad411e51ec0a38daea75c24
child 90576 520ca2f9b4b7a729bf52d10ea67b04e841eab622
push id22366
push usermak77@bonardo.net
push dateThu, 29 Mar 2012 15:38:30 +0000
treeherdermozilla-central@ff3521bc6559 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersluke
milestone14.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Document macro naming style and struct naming style in C-compatible code, where C++ namespaces can't be used to avoid name collisions. No bug, r=luke over IRC, DONTBUILD because this is modifying docs but touching no code
mfbt/STYLE
--- a/mfbt/STYLE
+++ b/mfbt/STYLE
@@ -187,16 +187,22 @@ indented.
 
   namespace mozilla {
   ...
   } // namespace mozilla
 
 Don't use |using| in a header unless it's confined to a class or method.
 Implementation files for out-of-line functionality may use |using|.
 
+Name data structures and methods which must be usable in C code with a Moz*
+prefix, e.g. MozCustomStructure.  If the data structure is not meant to be used
+outside of the header in which it is found (i.e. it would be in mozilla::detail
+but for its being required to work in C code), add a corresponding comment to
+highlight this.
+
 == #includes ==
 
 Headers that include mfbt headers use a fully-qualified include path, even if
 full qualification is not strictly necessary.
 
   #include "mozilla/Assertions.h"
 
 mfbt headers should be included first, alphabetically.  Standard includes should
@@ -262,16 +268,21 @@ confusion test for it separately from gc
   #  endif
   #elif defined(_MSC_VER)
   #endif
 
 But don't distinguish clang's feature support using version checks: use the
 __has_feature() and __has_extension() macros instead, because vendors may
 customize clang's version numbers.
 
+Use a MOZ_* prefix when defining macros (e.g. MOZ_OVERRIDE, MOZ_LIKELY, and so
+on) that are part of the mfbt interface.  (C++ implementation files implementing
+mfbt's interface but which are not directly part of that interface may ignore
+this rule.)
+
 Prefer inline functions to macros whenever possible.
 
 == Comments ==
 
 Header files shall have a short descriptive comment underneath license
 boilerplate indicating what functionality the file implements, to be picked up
 by MXR and displayed in directory listings.  (But see bug 717196, which
 currently prevents MXR from doing this if the MPL2 boilerplate is used.)