From d63ae5a5fa3ae259abdcdbc97c16fbed4d0b98ae Mon Sep 17 00:00:00 2001 From: Piper Merriam Date: Wed, 16 Dec 2015 16:18:36 -0700 Subject: Flesh out naming convention section of docs --- docs/style-guide.rst | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 101 insertions(+), 1 deletion(-) (limited to 'docs/style-guide.rst') diff --git a/docs/style-guide.rst b/docs/style-guide.rst index cd901e63..4e9a0182 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -529,10 +529,110 @@ 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 recomendations 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) + +.. note:: When using abbreviations in CapWords, capitalize all the letters of the abbreviation. Thus HTTPServerError is better than HttpServerError. + + +The following naming conventions are discouraged. + +* ``mixedCase`` (differs from CapitalizedWords by initial lowercase character!) +* ``Capitalized_Words_With_Underscores`` + + +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 be lowercase with words separated by underscores. + + +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``. + + +Contract and Local Variables +============================ + +Use lowercase words separated by underscores. Use trailing underscores to +avoid collisions with reserved names. + + +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 ======================= -- cgit From d1882bc7539865ef067c65f9d9dc074ca9530a8a Mon Sep 17 00:00:00 2001 From: Piper Merriam Date: Thu, 17 Dec 2015 08:57:02 -0700 Subject: use mixedCase --- docs/style-guide.rst | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) (limited to 'docs/style-guide.rst') diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 4e9a0182..2c979296 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -559,15 +559,11 @@ naming styles. * ``UPPERCASE`` * ``UPPER_CASE_WITH_UNDERSCORES`` * ``CapitalizedWords`` (or CapWords) - -.. note:: When using abbreviations in CapWords, capitalize all the letters of the abbreviation. Thus HTTPServerError is better than HttpServerError. - - -The following naming conventions are discouraged. - * ``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 ============== @@ -595,7 +591,7 @@ Events should be named using the CapWords style. Function Names ============== -Functions should be lowercase with words separated by underscores. +Functions should use mixedCase. Function Arguments @@ -608,8 +604,7 @@ should be the first argument and should always be named ``self``. Contract and Local Variables ============================ -Use lowercase words separated by underscores. Use trailing underscores to -avoid collisions with reserved names. +Use mixedCase. Constants -- cgit From 3af5db99b8239899935286844aa8f053f94af9a4 Mon Sep 17 00:00:00 2001 From: Piper Merriam Date: Wed, 6 Jan 2016 16:26:08 -0700 Subject: fix spelling and heading title --- docs/style-guide.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/style-guide.rst') diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 2c979296..0e782e23 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -538,7 +538,7 @@ 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 recomendations given here are intended to improve the readability, +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. @@ -601,8 +601,8 @@ When writing library functions that operate on a custom struct, the struct should be the first argument and should always be named ``self``. -Contract and Local Variables -============================ +Local and State Variables +========================= Use mixedCase. -- cgit