Merge pull request #306 from pipermerriam/piper/flesh-out-naming-conventions

Flesh out naming convention in the Style Guide

1 files changed, 96 insertions, 1 deletions

diff --git a/docs/style-guide.rst b/docs/style-guide.rst
index cd901e63..0e782e23 100644
--- a/docs/style-guide.rst
+++ b/docs/style-guide.rst
@@ -529,10 +529,105 @@ No::
     x = y+z;
     x +=1;
 
+
+******************
 Naming Conventions
+******************
+
+Naming conventions are powerful when adopted and used broadly.  The use of
+different conventions can convey significant *meta* information that would
+otherwise not be immediately available.
+
+The naming recommendations given here are intended to improve the readability,
+and thus they are not rules, but rather guidelines to try and help convey the
+most information through the names of things.
+
+Lastly, consistency within a codebase should always supercede any conventions
+outlined in this document.
+
+
+Naming Styles
+=============
+
+To avoid confusion, the following names will be used to refer to different
+naming styles.
+
+* ``b`` (single lowercase letter)
+* ``B`` (single uppercase letter)
+* ``lowercase``
+* ``lower_case_with_underscores``
+* ``UPPERCASE``
+* ``UPPER_CASE_WITH_UNDERSCORES``
+* ``CapitalizedWords`` (or CapWords)
+* ``mixedCase`` (differs from CapitalizedWords by initial lowercase character!)
+* ``Capitalized_Words_With_Underscores``
+
+.. note:: When using abbreviations in CapWords, capitalize all the letters of the abbreviation. Thus HTTPServerError is better than HttpServerError.
+
+
+Names to Avoid
+==============
+
+* ``l`` - Lowercase letter el
+* ``O`` - Uppercase letter oh
+* ``I`` - Uppercase letter eye
+
+Never use any of these for single letter variable names.  They are often
+indistinguishable from the numerals one and zero.
+
+
+Contract and Library Names
+==========================
+
+Contracts should be named using the CapWords style.
+
+
+Events
+======
+
+Events should be named using the CapWords style.
+
+
+Function Names
+==============
+
+Functions should use mixedCase.
+
+
+Function Arguments
 ==================
 
-TODO
+When writing library functions that operate on a custom struct, the struct
+should be the first argument and should always be named ``self``.
+
+
+Local and State Variables
+=========================
+
+Use mixedCase.
+
+
+Constants
+=========
+
+Constants should be named with all capital letters with underscores separating
+words.  (for example:``MAX_BLOCKS``)
+
+
+Modifiers
+=========
+
+Function modifiers should use lowercase words separated by underscores.
+
+
+Avoiding Collisions
+===================
+
+* ``single_trailing_underscore_``
+
+This convention is suggested when the desired name collides with that of a
+built-in or otherwise reserved name.
+
 
 General Recommendations
 =======================