Project

General

Profile

CodeStyle » History » Revision 21

Revision 20 (Alex Afanasyev, 04/01/2014 01:52 PM) → Revision 21/30 (Alex Afanasyev, 04/01/2014 01:53 PM)

# NFD code style guidelines 

 NFD adopts [NDN Platform C++, C, C#, Java and JavaScript Code Guidelines](http://named-data.net/codebase/platform/documentation/ndn-platform-development-guidelines/cpp-code-guidelines/), with the following exceptions: 

 *     (amended 8) Names representing generic template types should be a single uppercase letter 

         template<class T> ... 
         template<class C, class D> ... 

     However, when template parameter represents a certain concept and expected to have a certain interface, the name should be explicitly spelled out: 

         template<class FaceBase> ... 
         template<class Packet> ... 

 *     (amended 10) 
     Global variables should have `g_` prefix 

 *     (amended 11) 
     **Private** class variables should have `m_` prefix. 
     **Static** class variables should have `s_` prefix. 

 *     (amended 26) 
     Allow commonly used abbreviated **next/prev** pair in addition to **next/previous** 

     Pair **insert/erase** should be used for any new code, already implemented code can keep **insert/delete** if it does not conflict with C++ delete keyword. 

 *     (amended 27) 
     In cases when full word is too long, a commonly accepted abbreviation can be used.    For example, **dest** instead of **destination**. 

 *     (amended 31) 
     Exceptions can be used in the code, but should be used only in **exceptional** cases and not in the primary processing path. 

     Exceptions can be suffixed with either `Exception` (eg. SecurityException) or `Error` (eg. SecurityError).    Alternatively (and it is a recommended method), one should declare exception class `Exception` or `Error` as an inner class, from which the exception is thrown. For example, when declaring class Foo that can throw errors, one can write the following: 

         #include <stdexcept> 
        
         class Foo 
         { 
           class Error : std::runtime_exception 
           { 
           public: 
             explicit 
             Error(const std::string& what) 
               : std::runtime_error(what) 
             { 
             } 
           }; 
         };   

     In addition to that, if class Foo is a base class or interface for some class hierarchy, then child classes should should define their own `Error` or `Exception` classes that are inherited from the parent's Error class. 

 *     (amended 33) 
     We will use only `.cpp` and `.hpp` extensions 

 *     (removed 35) 
     Lines should be within a reasonable range. Lines longer than 100 columns should generally be avoided. 

 *     (updated 37) 
     Exceptions: 

     * The following is the standard practice with ``operator<<``: 

             std::cout << "Something here " 
                       << "Something there" << std::endl; 

 *     (removed 44) 
     Implicit conversion is generally allowed. 

     Implicit conversion between integer and floating point numbers can cause problems and should be avoided. 

     Implicit conversion in single-argument constructor is usually undesirable. Therefore, all single-argument constructors should be marked 'explicit', unless implicit conversion is desirable. In that case, a comment should document the reason. 

     Avoid C-style casts.    Use `static_cast`, `dynamic_cast`, `reinterpret_cast`, `const_cast` instead where appropriate.    Use `static_pointer_cast`, `dynamic_pointer_cast`, `const_pointer_cast` when dealing with `shared_ptr`. 

 *     (replaced 48) 
     In most cases, class instance variables should never be declared public. 
    
     The concepts of information hiding and encapsulation are violated by public variables. Use private variables and access methods instead. One exception to this rule is when the class is essentially a dumb data structure with no behavior (equivalent to a C struct, also known as PODS).    In this case it is appropriate to make the instance variables public by using ``struct``. 

 *     (amended 68) 
     All three presented styles ARE acceptable.    First and third ARE recommended (these are actually GNU styles). 

 *     (amended 69) 
     The class declarations should have the following form: 

         class SomeClass : public BaseClass  
         {  
         public:  
           ... <public methods> ... 
         protected:  
           ... <protected methods> ... 
         private:  
           ... <private methods> ... 
        
         public:  
           ... <public data> ... 
         protected:  
           ... <protected data> ... 
         private:  
           ... <private data> ... 
         }; 

     ``public``, ``protected``, ``private`` may be repeated several times without interleaving (e.g. public, public, public, private, private) if this allows better readability of the code. 

 *     (amended 70) 
     When declaring/defining function/method, the return type should be put on a separate line before function/method name. 

     Method and function definitions should have the following form: 

         void 
         someMethod()  
         {  
           ...  
         } 

 *     (amended 76) No space requirement before : in switch statements 

         switch (condition) {  
           case ABC: 
             statements;  
             // Fallthrough  
        
           case DEF:  
             statements;  
             break; 
        
           case XYZ:  
             statements;  
             break;  
        
           default:  
             statements;  
             break; 
         }     

 ## Python addition 

 Most of the provisions in the above style guidance apply to Python as well.    For python-specific elements, [PEP 8](http://legacy.python.org/dev/peps/pep-0008/) can be used as a reference coding style.   

 The following is few rules directly adopted from [PEP 8](http://legacy.python.org/dev/peps/pep-0008/): 

 * **P1**    Always surround these binary operators with a single space on either side: assignment (=), augmented assignment (+=, -= etc.), comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not), Booleans (and, or, not). 

         def complex(real, imag=0.0): 
             value = 1.1 
             return magic(r=real + value, i=imag) 

 * **P2** Don't use spaces around the = sign when used to indicate a keyword argument or a default parameter value. 

         def complex(real, imag=0.0): 
             return magic(r=real, i=imag)