The Element Style of C++

 

 

---

Contents

0. Key Words

1. Introduction

2. General Principles

3. Fomatting Convetions

4. Naming Convetions

5. Documentation Convetions

 

---

Key Words

 

         characteristics; character; convention; effectiveness; capitalization; punctuation; exponential;

         indentation; typographic arrangement; no regard to;predictable; emphasize; inplementation;    

         anticipate;prefessionalism; foresight; deviation; implementation; wrap; truncate; delineate;  

         devoid; harizontally; abbreviation; generic; sufficient; adequately; excessively; vowel; consonant; ambiguity; reduce; differentiate; equivalent; perspective; enumerations;

         specification; self-explanatory; index; cross-reference; elegant; inspection; adjacent; intervening; synoptic; interfere; indicate; inapplicable; lifespan; assumption; allocate; workaround; publicize; isolate;

 

一.Introduction

 

        The positive reception to that book, coupled with recurring questions about C++ style issues,resulted in the edition for C++.

          This is deliberate, as many of the programming principles descried are timeless and valid across programming languages.

          The syntax of a programming language tells you what code it is possible to write——what machines will understand; Style tells you what you ought to write——what humans reading the code will understand.

 

二 .General Principles

        Simplicity

        Build simple classes and simple methods,Determine how much you need to do to meet the expectatios of your users.

        Clarity

        Ensure that each class,interface,method,variable and object has a clear purpose. Explain where, when, why and how to use each.

        Completeness

        Provide the mininum functionality that any reasonable user would expect to find and use. Create complete documentation. document all features and functionality.

        Consistency

        Similar entities should look and behave the same; dissimilar entities should look and behave differently. Create and apply standards whenever possible.

        Robustness

        Provide predictable, documented behavior in response to errors and exceptions. Do not hide errors and do not force clients to detect erros.

 

三. Formatting Convetions

       Break long statements into mutiple lines.

        Use a single space to seperate the keywords, parentheses, and curly braces in condition statements.

        Use a single space on either side of binary operators, except for the "." or "->" operators.

        Use blank lines to seperate each logical section in a method implementation.  

        Use blank lines to seperate each function definition in a source file.              

 

四.  Naming Convetions

       the function declaration / the function definition.

         4.1 Preprocessor Macro Names

                ---------Use UPPERCASE and Underscores  for Preprocessor Macro Names;

                ---------Use a unique prefix to Macro Names;  

         4.2 Type and Constant Names

                ---------Use "UpperCamelCase" for Classes, Constants, Structures, Enumerations and Typedefs;

                ---------Use Nouns to Name Compound Types;  

                ---------Pluralize the Names of Collections;

         4.3 Function Names

                ---------Use "LowerCamelCase" for Function Names;

                ---------Use Verbs to Name Functions;

                ---------Use "is", "get", "set" to Name Accessor and Mutator Functions;    

                ------------------Your classes should provide read access to Boolean members using functions that begin with the word "is".  

                ------------------Your classes should provide read access to other members using functions that begin with the word "get".

                ------------------Your classes should provide read access to indexed members using a "get" function that takes a size_t index argument.

                ------------------Your classes should provide writhe access to members using functions that begin with the word "set".

 

 

                ---------Use Nouns to Names Variables.

                ---------Pluralize variables that identify collections. 

                ---------Name All Function Parameters.

                ---------Use other for Parameter Names in Copy Constructors and Assignment Operators.

                ---------Give Function Parameter the Same Name as the Member Variables you Assigned Them to. 

         4.4 Variable and Parameter Names

                ---------Use "LowerCamelCase" for Variable and Function Parameter Names;

          4.5 General Principles

                ---------Use Meaningful Names;

                ---------Use Familiar Namas;

                ---------Avoid the Use of Digits within Names;

                ---------Avoid Excessively Long Names;

                ---------Join the Vowel Generations——Use Complete Words.

                ---------Use "LowerCamelCase" for Abbreviations.

                ---------Do Not Use Case to Differentiate Names.

           **If you find yourself removing vowels simply to shorten a long name, then you need to qusetion whether the original name is appropriate.

           **Instead of simply giving the entity a new name that conveys less meaning, first reconsider its design or purpose. A refactoring of the entity may produce new classes, interfaces, methods, or variables that are more focued and  can be more meaningful yet simpler names. 

五

.  Documentation Convetions

         5.1 Document the softwear interfaces for those who must use it.

         5.2 Document the implementation for those who must maintian it.

         5.3 Keep the Comments and Code Synthronized. 

         5.4 Embed  API Reference Documentaion in the souce code.  

         5.5 Generate  API Reference Documentaion directely from the souce code.  

         5.6 Document All Significate Software Elements.  

         5.7 Document Software Elements as Early as possible.  

         5.8 Use Block Comments to Discribe the Programming Interface.

         5.9 Use one-Line Comments to Explain Implementation Details. 

                ---------The Purpose of specific variable or expressions.

                ---------Any implementation-level design decisions.

                ---------The source material for complex algorithms.

                ---------Defect fixes or workarounds.

                ---------Code that may benefit from further optimization or elaboration.

                ---------Any Known Problems, limitations, and deficiencies.

         5.10 Use a single Consistent Format and Organization for All Documentation Comments.

         5.11 Provide a Summary Description of Every Declared Element. 

         5.12 Document the Interface Exposed by Every Function.

         5.13 Document Thread Synchronization Requirements.

         5.14 Provide Examples to Illustrate Common and Proper Usage.  

         5.15 Document Important Preconditions, Postconditions and Invariant Conditions. 

         5.16 Document Known Defects and Deficiencies.  

         5.17 Use Active Voice to Describe Actors and Passive Voice to Describe Actions.  

         5.18 Use "This" rather than "The" when Referring to Instances of the Current Class.  

         5.19 Explain Why the code dose What it dose. 

         5.20 Avoid the use of End-Line Comments.

 

         5.22 Add a "fall-through" Comment beween Two Case labels if no break statement seperates those lables.

         5.23 Use Keywords to Mark Pending work, Unresovled Issues, Defects, and Bug Fixes.