Coding Guidelines. Coding guidelines. Contents

Transcription

1 Coding Guidelines Coding guidelines The following is a set of guidelines that must be followed by all NEMO5 developers. They are based on the Google C++ Style guide, though not all guidelines are followed in NEMO5. For the complete list of guidelines used by Google, click here. Use the table of contents to navigate each section: Contents 1 Coding guidelines 1.1 Include/define guards 1.2 Inline functions 1.3 Function parameter ordering 1.4 Include order 1.5 Namespaces 1.6 Nested classes allowed 1.7 Static member functions, global functions 1.8 Local variables 1.9 Static or global variables 1.10 Constructors 1.11 If your class defines member variables, initialize to appropriate values. Pointers as NULL. STL containers can be an exception 1.12 Copy and assignment constructors 1.13 Structs 1.14 Inheritance 1.15 Interface classes 1.16 Multiple inheritance 1.17 Operator overloading 1.18 Private variable accessors 1.19 Write short functions 1.20 Ownership and memory management 1.21 Encourage const reference if the object is not a pointer it must be passed by reference 1.22 Default parameters 1.23 Variable-length arrays and alloca() 1.24 Class friendship 1.25 Exceptions 1.26 Dynamic casts 1.27 Avoid C-style casts 1.28 Printing to screen 1.29 Increment/decrement operators 1.30 const variables 1 / 22

2 1.31 Macros and inline functions 1.32 Null usage 1.33 Boost 1.34 Naming conventions Class (type) names File names Output File names Function names Variable names 1.35 Macro names 1.36 Commented code should be deleted ASAP 1.37 License header, general purpose, contact info 1.38 Every member variable and function should be documented using Doxygen 1.39 SVN properties 1.40 Code and input deck formatting whitespace 1.41 New and delete 1.42 Allocation and deallocation of STL containers 1.43 Compile and test your code before committing 1.44 Document all input deck solver options 2 References Include/define guards All header files should include define guards. Define guards are used in C++ header files (*.h) to avoid multiple inclusion, which results in compiler errors. #ifndef NEMO_INCLUDE_<PATH>_<FILENAME>_H_ #define NEMO_INCLUDE_<PATH>_<FILENAME>_H_ /* Includes */ /* Code */ #endif Define guards are preprocessor directives that are skipped at #ifndef whenever NEMO_INCLUDE_<PATH>_<FILENAME>_H_ has already been defined by the #define directive. Define guards should be included in all header files and should display the path and 2 / 22

3 header file name as shown. Inline functions Short functions that are called often should be inline. Inline functions are functions that are saved directly to memory by the compiler so that each function call can be done quickly and efficiently. Because of this, inline functions should be very small (a few lines long). Small functions that are called many times should be inline. Example: //Declaration in header file: inline int DOFmap::get_number_of_dofs(void) return number_of_dofs; This often used function contains only a single line, so it should be inline. If you are unsure whether a function should be inline, please ask a NEMO5 core developer. Function parameter ordering Inputs should be defined before outputs in function parameters Example: //Definition: void Propagation::get_data(const std::string& variable, double& dat a) if (variable=="current") calculate_current(); data = current; 3 / 22

4 In this example, variable is an input and data is an ouput. There may be exceptions, such as when input has a default parameter. Example: //Declaration: virtual void get_data(const std::string& variable, const std::vector <NemoMeshPoint>* momentum, const PetscMatrixParallelComplex*& Matrix, const DOFmap* row_dof_map=null, const DOFmap * col_dofmap=null); In this case, Matrix is an output, but row_dof_map and col_dofmap are inputs that are placed until the end because they have a default value. Default parameters are included in some functions so that their values do not need to be explicitly passed as arguments when called. Include order #include preprocessor directives should be included as follows: In.h files, includes should be in the following order: standard C header files, standard C++ header files, external library header files, NEMO5 header files. Header files in each of these sections should be ordered alphabetically. Example: //Common C header file #include "mpi.h" //Standard C++ header files #include <complex> #include <map> #include <sstream> //External library header files #include <boost/unordered_set.hpp> //Local NEMO5 header files #include "Propagator.h" #include "Nemo.h" #include "NemoFactory.h" #include "ReferenceCountedObject.h" #include "Simulation.h" 4 / 22

5 In.cpp files, includes should be in the following order: header file with current.cpp file s declarations, standard C header files, standard C++ header files, external library header files, NEMO5 header files. Header files in each of these sections should be ordered alphabetically. Example (from Repartition.cpp): //Header file with declarations for this file #include "Repartition.h" //Standard C++ header files #include <iostream> #include <sstream> //NEMO5 header files #include "Atom.h" #include "AtomStructNode.h" #include "PseudomorphicDomain.h" #include "Simulation.h" The reason for this ordering is mainly readability, but it can also avoid some compilation problems as noted here. Namespaces Namespace usage is discouraged. Namespaces allow the developer to use a set of functions in the scope following the using namespace directive. For example: using namespace std; //std::out is implied out << "Test output to std::out\n"; This is discouraged, however. Using a namespace would force any function that is part of a namespace called after the using directive to be used, when another function call was 5 / 22

6 intended. To specify which namespace a function is a part of, explicitly state it in the function call. Example: std::out << "Test output to std::out\n"; Nested classes allowed Nested classes are allowed in NEMO5. Nested classes are classes that are defined in other classes. Static member functions, global functions Use static member functions when necessary. Do not use global functions Static member functions are functions that may be used without the requirement of creating an object. In NEMO5, these functions are usually called with its class explicitly shown as follows in this matrix-vector multiplication example: //Classname::function(argument1, argument2, etc); PetscMatrixParallelComplex::mult(*M1_matrix,M_vectors_temp,M_vectors 1); Global functions are functions declared outside the scope of any class/function of the code. It can be called from anywhere in the code. Static member functions are similar to functions of global scope, but global functions are not allowed in NEMO5. Static member functions should only be used whenever absolutely necessary. Always try to call functions from a created object. Local variables Local variables should have the narrowest scope possible. Local variables are variables that are only known within the scope of a certain function or code block. When a variable is declared inside a code block, it is only known within the code block; it is discarded upon exiting the block. 6 / 22

7 Example: void function(arg1, arg2) //function_variable is known throughout the entire function int function_variable = 0; //New block begins if (enter == true) //block_variable is known only inside the if statement code bloc k int block_variable = 0; //The block ends, so block_variable is no longer known by the func tion If a variable is only used in the innermost block, it should be declared inside the block. Doing so prevents overwriting of a variable being used by another section of the code. It also improves readability since variable declarations are closer to their modifications. Static or global variables Static or global variables are forbidden in NEMO5 Variables should be kept object-specific. Variables should not be shared by several objects. Static variables can cause data corruption when used by multiple threads or MPI ranks when the variable is shared. Constructors Constructors should never contain any complex initialization such as function calls, especially if said inititialization can fail. Constructors are functions that are called upon construction of an object. Their name always matches the name of the object s class type. An example of a constructor in NEMO5 is: GreenModule::GreenModule() 7 / 22

8 this_domain_hamilton_constructor = NULL; auxiliary_propagation_inv = NULL; this_domain_hamilton_constructor_initialized=false; auxiliary_propagation_inv_initialized=false; Constructors should only contain very short initialization procedures, such as variable and pointer initialization as shown above. If your class defines member variables, initialize to appropriate values. Pointers as NULL. STL containers can be an exception Member variables should be initialized before use. Example: PetscMatrixParallelComplex *matrix1 = NULL; PetscMatrixParallelComplex *matrix2 = NULL; Using uninitialized variables may lead to unpredictable behavior (and compiler warnings). Not initializing pointers to NULL can be especially troublesome if logic in the code expects this pointer to be initialized. Many portions of the Propagation infrastructure require that a pointer be NULL to show that it has not been initialized yet. For example: if(drain_solver!=null&&source_solver==null) right_hand_side = drain_small_right_hand_side; right_hand_side = new PetscMatrixParallelComplex(number_of_own_sup er_rows,number_of_rhs_columns,mpi_comm_self); right_hand_side->set_num_owned_rows(right_hand_side->get_num_rows( )); right_hand_side->consider_as_full(); right_hand_side->allocate_memory(); right_hand_side->set_to_zero(); 8 / 22

9 In this important part of the QTBM algorithm in NEMO5, the right-hand-side of the drain would be initialized even when it shouldn t as long as drain_solver had some non-null value. This would lead to unpredictable results. Copy and assignment constructors Only use copy and assignment constructors when necessary. Copy constructors allow the programmer to create a new object by value. In other words, data is duplicated. For example: //just copy the self-energy to full_self_matrix full_self_matrix = new PetscMatrixParallelComplex(*small_self_ma trix); Copying is usually not required as pointers allow data to be shared. Data duplication can lead to excessive memory usage. Structs Do not use structs. Structs are data structures that can contain any type of data (variables, arrays, other structs, etc.) with the exception of functions. Structs are normally used in C. C++ objects have virtually replaced structs, so using objects as data structures is preferred. Inheritance Composition is often more appropriate than inheritance. C++ provides the useful capability of inheritance, allowing one to create child classes from base (parent) classes. This child class is able to perform most of what the base class can, in addition to child-specific capabilities. However, relying on inheritance can create difficult to manage code. One of the most important aspects of composition is the ability to use classes as interfaces to other classes. By using a class as an interface, one may use only certain utilities, while by inheriting from a base class one must inherit everything. One problem could arise for example, 9 / 22

10 when one needs to create a child class but wants to inherit from a new base class. One would need to copy code to a new child class, which can become confusing when done too often. This link explains why composition may be preferrable: Composition over inheritance Interface classes An interface class may be used and should contain the word Interface as a suffix to the class Interface classes are classes with only purely virtual classes and static member variables. Purely static member functions are virtual functions declared with a = 0 so that they must be inherited through polymorphism to be used. For example: virtual void interface_function(/*...*/) = 0; Failure to inherit this variable would result in a compiler error. Multiple inheritance Use multiple inheritance only when absolutely necessary. When defining a class, one may specify multiple base classes For example: class QTBMModule : public PropagationModule, public OtherClassToInhe ritfrom //Can use protected and public members of PropagationModule and Ot herclasstoinheritfrom Rarely is this ever needed, and can sometimes cause conflicts when a derived class inherits from two classes that contain a function with the same name and signature. Multiple inheritance should only ever be used when one of the classes is an interface class. Operator overloading 10 / 22

11 Operator overloading is prohibited except under rare circumstances and should only be performed by experienced developers. Overloading operators such as + and = is possible in C++ and works similarly to overloading functions. One common example of operator overloading is changing the use of + and = to accomodate the addition of complex numbers. Such an example is shown here Operator overloading. One usually does this for convenience rather than requirement. And it is easy to see that overloading a common operator anywhere in the code would be confusing to people reading your code without knowing about the overloading. Because of this, operator overloading should not be done unless approved by the core NEMO5 team. Private variable accessors Classes should contain private member variables that are only accessible through public accessors. Private variable accessors, also known as getters and setters, are public functions that can be used by any class to obtain (get) or modify (set) a private variable of an object. This is preferrable to the object s class having a publicly available variable that can be obtained and modified by any other class. Getters and setters also allow developers to easily see how data flow should be managed. For example, using a getter that can only return a vector only allows the developer to use that specific vector which was intended to be used. An example of a public accessor obtaining a private member variable is as follows: class GetPrivateInt public: int getter() return private_integer; private: int private_integer; Write short functions Functions should perform the most minimal operation in an algorithm. 11 / 22

12 Functions should very rarely (preferable never) be more than about 100 lines long. Code is much easier to read if divided into functions that represent fundamental steps in an algorithm. Each step should include its own algorithm divided into its fundamental steps. This also allows sections of code to be easily reused through fundamental function calls without needing to duplicate any actual code. Also, finding bugs in code that is used through function calls, not simply copied, is a much simpler task since the problem is more likely to be isolated to a single point. For example: void QTBM::do_solve_inverse(...) obtain_hamiltonian(...); obtain_self_energies(...); prepare_lhs(...); prepare_rhs(...); add_self_energies(...); if (solver == "compression") call_compression(...); else if (solver == "mumps") call_mumps(...); else if (solver == "pardiso") call_pardiso(...); result = inverted_matrix; Ownership and memory management Memory management can get complicated in object oriented programming and care must be taken when creating and destroying data. Data that is created by one object does not necessarily need to be destroyed by the same object. Often, other objects can claim ownership of data and it is the responsibility of that object to destroy (deallocate) the data once it has been used. Keeping track of data ownership can be confusing, so must be well thought out to avoid memory leaks that can cause simulations to run out of memory. Encourage const reference if the object is not a pointer it must be passed by reference Passing const type references are encouraged when the passed reference is not to be changed. 12 / 22

13 Adding the type const before any data type restricts the developer from modifying the variable. Accidentally modifying a variable, pointer or object could result in unpredictable behavior, and the const declaration prevents the program from modifying it. Attempting to modifying the variable would result in a compilation error. Passing by reference is done in C++ using the & operator in the declaration. It is similar to a pointer in that it points to the address of another object or variable but can sometimes simplify code and make it more readable. Declaring a parameter const and a reference go hand in hand when a reference must be passed to a function that points to a value that must never be changed by the program. An example of syntax: virtual void assemble_position_operator(const std::string& r, PetscM atrixparallelcomplex*& position); Here, the string value referenced by the variable r must never be changed by the function, so a const reference is passed to it. Default parameters Default parameters must only be used when absolutely necessary. When declaring a function, one can define (not only declare) the last parameter. For example: static void invert(petscmatrixparallelcomplex& A, PetscMatrixParalle lcomplex** result_ptr, const std::string factorization_solver="mumps") ; In this example, the string factorization_solver is set to mumps by default. What this does is that it allows the developer using the function to be able to both specify a new value for factorization_solver or leave the argument blank. By leaving the argument blank, the default is used. The problem with this is that comparison of the declaration and use of a function with default parameters may cause some confusion, since the function s signatures do not always match. 13 / 22

14 Variable-length arrays and alloca() Variable-length arrays and alloca() are not allowed Variable-length arrays and alloca() are used to allocate memory on the stack instead of the heap. They allow for more efficient memory allocation, but are not standard in C++. In addition, memory problems are harder to track in the stack than in the heap. Class friendship Friend functions should be avoided. The friend keyword allows specific classes to access otherwise private or protected member functions of a class. One must be careful with friend as this can defeat the purpose of encapsulation, an important aspect of C++. Exceptions Exceptions must be added in NEMO5 when possible. A meaningful message must be shown upon reaching an exception. Exceptions must not be used for control flow. Exceptions are a useful way to stopping a program s execution when something that should not occur occurs. They are useful for avoiding situations such as segmentation faults where the user cannot easily know why the program crashed. Dynamic casts Avoid using dynamic casts. dynamic_cast allows the programmer to change the type of class of an object. It is the safest way to downcast an object, in other words, turn a base object into a child object. Remember that the base object does not need to be deleted after conversion. The syntax is shown in this example: Simulation* base_object; Propagation* new_object = dynamic_cast<propagation*>(base_object); //base_object effectively become new_object of type Propagation, which inherits from base_object's Simulation class. Although sometimes useful, it usually means the code s design is flawed and probably not well planned-out. Setting up a proper hierarchy based on polymorphism and inheritance should 14 / 22

15 always be preffered over a dynamic cast. Dynamic casts can make the code hard to maintain since decisions regarding class types must be made in the code as opposed to being handled by an already existing class hierarchy. Avoid C-style casts Use C++ casts instead of C casts. C++ casts like static_cast and dynamic_cast are preferred over C-style casts like y = (int)x C casts are sometimes ambugous, since they may be performing a conversion or cast using the same syntax. They should be avoided. Printing to screen Do not use printf, cout, cerr, etc. for output to screen Several output macros have been designated for outputting messages to the terminal. Whether the messages streamed to the macros is determined by whether the message level is greater than or equal to the option messaging_level in the Global section of the input deck. OUT_ERROR // Highest level, error messages MUST be shown! OUT_WARNING // Level for warnings (may be encountered a couple of t imes - not every warning is bad), output if messaging_level is 1 or hi gher OUT_NORMAL // Normal output, output if messaging_level is 2 or hig her OUT_DETAILED // Some more detailed information, output if messaging_ level is 3 or higher OUT_DEBUG // Only for debugging, output if messaging_level is 4 o r higher Example: OUT_NORMAL << "This message is seen on screen if option messaging_leve l is 2 or higher.\n"; OUT_DEBUG << "This message will not be seen unless messaging_level is 4 or 5.\n"; Increment/decrement operators 15 / 22

16 Use the pre-increment/decrement as opposed to post-increment/decrement operator int i = 0; ++i; //Pre-increment i++; //Post-increment Pre-incrementing and post-incrementing normally does not change performance of code much, but the performance of pre-increment/decrement is never worse than postincrement/decrement. This is especially true in the case of iterators. This is because post increment/decrement requires a copy of the variable or iterator to be made. This can be avoided when using pre-increment/decrement operators. const variables Use of const data types is encouraged where it makes sense. const is a type identifier that can provide your code with some welcome sanity checks. It prevents variables, STL containers, pointers, objects, etc., from being modified accidentally when it is known they must never be modified. Often, input variables that are defined only once (such as constants), are good candidates for being const. Syntax: const int variable; variable = 99; //Compile will detect an error here. One must be careful when using const if it can be predicted that a variable may change in the future. The variable must stay const throughout its use in the code, meaning it can not be modified. This can provide headaches to other programmers that need to modify the variable. Macros and inline functions Be cautious with macros. Inline functions are preferred. Macros are similar to functions, but are replaced by the compiler by the argument which is defined using the #define pre-processor directive. For example, macros to find a minimum and maximum of two values are shown: 16 / 22

17 #define MIN(a,b) (((a)<(b))?(a):(b)) #define MAX(a,b) (((a)>(b))?(a):(b)) Macros can provide performance boosts when compared to functions, since the compiler directly replaces the macro with whatever it s defined to be. However, this is often unnecessary in C++, where inline functions provide similar performance boosts while retaining the same functionality of functions. Use and syntax of inline functions is provided in this document. Null usage Always initialize all pointers to NULL when declaring them. Initializing a pointer is important to avoid unpredictable behavior. By not defining a pointer as NULL, a random address is given to it, which could lead to the code using uninitialized memory and causing a segmentation fault. NEMO5 often checks whether an object pointer is NULL and takes appropriate action to initialize it properly. When the pointer is not defined as NULL, an important step in an algorithm may be skipped and the uninitialized memory address read/write may be attempted. Boost Boost may be used. Boost is a collection of open-source C++ libraries that provide API support for useful tasks ranging from multithreading to image processing. The most commonly used set of Boost libraries used in NEMO5 is Boost Spirit, which provides an API for parsing texting files. If you you want to use a certain Boost functionality, contact one of the core NEMO5 developers for approval. Naming conventions Class (type) names Use CamelCase beginning with a capital letter for class names. For example, class PetscMatrixParallelComplex File names File names should always be the same name as the class declared/defined inside. For example, Propagation.cpp and Propagation.h should only hold the Propagation class. Only one class should be declared/defined in each set of.cpp and.h files. File names should not have underscores in the name. For example: PetscMatrixParallelComplex.cpp, 17 / 22

18 PetscMatrixParallelComplex.h Output File names All file output should be through the output collector and set as RESULTS, DEBUG or REPORT. Key solver outputs outputs should go to FINAL. REPORT is for logs, etc, and DEBUG should be used for less important output files, for example, iterative solution output. Output file names should fully describe the output. No hierarchical output directory system other than RESULTS, DEBUG or REPORT. All solvers should allow do_output to control whether the solver outputs any data files. Function names Use only lower case characters for function names (with the exception of names containing acronyms, like QTBM and RGF). Underscores are permitted. Function names should very clearly depict their purpose. For example: get_data(...) and do_solve_inverse(...) Variable names Variable names should be lowercase. Most importantly, variable names should clearly describe their function. Do NOT use vague acronyms for variable names that only you, the developer, understand. Simply adding comments on the side of the declaration will not make vague variable names easier to understand. Variable names should be as self-documenting as possible. For an example of bad variable names: PetscMatrixParallelComplexDouble* RCH = NULL; //It's unlikely that peo ple will know what this means PetscMatrixParallelComplexDouble* LCH = NULL; PetscMatrixParallelComplexDouble* OSH = NULL; Instead, use variable names that clearly describe the variable s purpose. For example: PetscMatrixParallelComplexDouble* right_coupling_hamiltonian = NULL; PetscMatrixParallelComplexDouble* left_coupling_hamiltonian = NULL; PetscMatrixParallelComplexDouble* on_site_hamiltonian = NULL; 18 / 22

19 Macro names Although not encouranged, if you absolutely must define a macro, use only upper-case letters and underscores. Use only capital letters and underscores, so a macro is not confused for a function. For example: #define THE_ANSWER_TO_LIFE_THE_UNIVERSE_AND_EVERYTHING 42 Commented code should be deleted ASAP Delete commented-out blocks of code as soon as you are done with it. It s understandable to have large blocks of code commented out when testing. However, NEMO5 has had an issue of enormous blocks of commented-out code lingering for months, even years. Do not let commented-out code linger for longer than necessary. License header, general purpose, contact info Always include license info, contact info and documentation in code. Template have been provided for you here for license info, contact info and documentation. You are responsible for making sure every required entry is filled upon creation of source files. Every member variable and function should be documented using Doxygen Functions, function parameters, classes and member variables should be documented using Doxygen. For a guide to documenting your code using Doxygen, see this page. To view current NEMO5 documentation using Doxygen, see this page. SVN properties Set proper syntax and file properties for SVN keywords. The $Id$ tag at the bottom of the license header must remain exactly as shown when adding a new file. This is expanded by subversion and shows file information such as revision number, last person to modify the file, and time committed to the repository. New files will not be automatically set to expand the SVN keywords, so they must be set using the svn propset command as follows: svn propset svn:keywords Id SourceFile.cpp If you don t to set this manually for each new file, you can 19 / 22

20 use SVN autoprops. The details can be found [ here Code and input deck formatting whitespace Lines should have a maximum of 160 characters for readability. Do NOT use tabs; always use 2 spaces. A recurring problem that has irked many NEMO5 developers is the lack of consistency of indentation and whitespace in source code and input decks. To avoid these inconsistencies it has been decided that tabs (\t) cannot be used for any reason. Also, there should only be 2 spaces per indentation. An example of code with correct whitespace: void function_name(bool correct_formatting) for (int i = 0; i < 100; ++i) if (this_is_true) no_tabs_ever(); correct_formatting = true; else never_use_tabs(); Do Not use pointer to a vector since vectors can re-allocate automatically and change address when the size changes. New and delete Always use the delete operator after using the new operator. The new C++ operator allocates memory and assigns it to a pointer. For example: PetscMatrixParallelComplex* my_matrix = new PetscMatrixParallelCompl 20 / 22

21 ex(/*constructor arguments*/); The parentheses in the example above are there so that the constructor of the class PetscMatrixParallelComplex is called. A class may contain many different constructors that all perform different initialization tasks. The most important thing about memory allocation using the new operator is that the memory assigned to the pointer must always be deallocated as some point within its scope using the delete operator. Not deleting a matrix within the scope of its allocation will result in memory leaks. A memory leak occurs when allocated memory can no longer be deallocated and can result in your process running out of memory. Proper use of new and delete is as follows: void create_use_and_delete_matrix() //The scope of my_matrix is only within this function PetscMatrixParallelComplex* my_matrix = new PetscMatrixParallelCompl ex(); use_matrix(my_matrix); //We are done using the allocated memory, so it must be deallocated within its scope delete my_matrix; //my_matrix would result in a memory leak if not deleted before the end of the function When pointers are passed as arguments, one must be careful when deallocating data with delete. Attempting to access this data after it has been deleted will result in a segmentation fault. Allocation and deallocation of STL containers STL containers such as vector, maps, set, etc do not need to be created with new and delete. They may be created normally being empty, and passed as pointer or reference to a function. They always allocate memory in the heap, this is different from C arrays. Also, if you do not use new and delete, memory will be always cleaned automatically. 21 / 22

22 Powered by TCPDF ( CODING GUIDELINES Compile and test your code before committing Never commit code that has not been compiled and tested and you are sure will not break NEMO5 or someone else code. Always make sure that when you change a.cpp or.h, your changes allow NEMO5 to compile and your change does not break your or someone else s code. This should be checked no matter how small the change and no matter how sure you are that your code change will not damage the integrity of NEMO5. Document all input deck solver options Use the available solver option documentation functions. For any new solver that is added to NEMO5, ensure that any solver option that is used is documented fully and properly. For more information, click here References Google codeguidelines 22 / 22