Difference between revisions of "Cogniteam/CodeConvention"

Revision as of 17:37, 30 December 2019

Git

TBD

Git Flow

TBD

Commits

TBD

ROS/ROS2

• If your project contains custom messages/services/actions, consider creating separate package projectname_msgs containing all messages/services/actions, don't put code in this package
• Create separate package for complex projects comprising many packages: 'projectname_launch, again, don't put code files here, it used for storing launch files/scripts and parameters/configuration files (see hamster_launch, lynx_launch)

Files and folders

C++

• Use C++14 standard <syntaxhighlight lang="cmake">

1. CMake

add_compile_options(-std=c++14) </syntaxhighlight>

• Use 4 spaces for tabbing
• Avoid typing more than 80 characters per line
• Prefer shared_ptr over pure pointers
• Prefer full names over short:
  • worldModel instead of wm
  • task_ instead of t_
  • calculateDistance() instead of calcDist()
• Use meaningful names for variables and methods (don't afraid to use long names):
  • distance not d
  • lastReceivedPosition_ not lastRP_
• Don't use too much general names for classes:
  • Icp2dMapAligner instead of MapAligner
  • VoxelGridMap instead of Map3d

Object-Oriented Programming

• Don't invent wheels - use best practices of object oriented programming and design patterns
• Make sure your are familiar with basic OOP principles (Inheritance, SRP, SOC, encapsulation, DI, etc...)
  • Object-Oriented Programming
  • SOLID Principles MUST READ
  • DRY Principle
  • KISS Principle
• Use new features provided by C++11 and C++14:
  • New features overview
  • C++11
  • C++14
• Use commonly known design patterns if they solve your problem:
  • Software design patterns
  • Design Patterns by Gang Of Four MUST READ

Convention names description

Naming conventions

   Single = 1,
   MultiPacket = 2,

   Red = 0x00,
   Green = 0x01,
   Blue = 0x02

Files and folders

Why not?

• http://www.stroustrup.com/bs_faq2.html#macro
• Try to debug this

Class template

Header file

<syntaxhighlight lang="C++"> /*

* CogniteamClass.h
* 
*  Created on: Jan 1, 2031
*      Author: John Doe <johndoe@cogniteam.com>
*
*
* Cogniteam LTD CONFIDENTIAL
*
* Unpublished Copyright (c) 2010-2020 Cogniteam,        All Rights Reserved.
*
* NOTICE:  All information contained  herein  is,  and  remains the property
* of Cogniteam.   The   intellectual   and   technical   concepts  contained
* herein are proprietary to Cogniteam and may  be  covered  by  Israeli  and
* Foreign Patents, patents in process,  and  are  protected  by trade secret
* or copyright law. Dissemination of  this  information  or  reproduction of
* this material is strictly forbidden unless  prior  written  permission  is
* obtained  from  Cogniteam.  Access  to  the  source  code contained herein
* is hereby   forbidden   to   anyone  except  current  Cogniteam employees,
* managers   or   contractors   who   have   executed   Confidentiality  and
* Non-disclosure    agreements    explicitly    covering     such     access
*
* The copyright notice  above  does  not  evidence  any  actual  or intended
* publication  or  disclosure    of    this  source  code,   which  includes
* information that is confidential  and/or  proprietary,  and  is  a   trade
* secret, of   Cogniteam.    ANY REPRODUCTION,  MODIFICATION,  DISTRIBUTION,
* PUBLIC   PERFORMANCE,  OR  PUBLIC  DISPLAY  OF  OR  THROUGH USE   OF  THIS
* SOURCE  CODE   WITHOUT   THE  EXPRESS  WRITTEN  CONSENT  OF  Cogniteam  IS
* STRICTLY PROHIBITED, AND IN VIOLATION OF APPLICABLE LAWS AND INTERNATIONAL
* TREATIES.  THE RECEIPT OR POSSESSION OF  THIS SOURCE  CODE  AND/OR RELATED
* INFORMATION DOES  NOT CONVEY OR IMPLY ANY RIGHTS  TO  REPRODUCE,  DISCLOSE
* OR  DISTRIBUTE ITS CONTENTS, OR TO  MANUFACTURE,  USE,  OR  SELL  ANYTHING
* THAT      IT     MAY     DESCRIBE,     IN     WHOLE     OR     IN     PART
*
*/
                        // Maximum 80 characters per line        // new line  
                                                                 // new line

// // Always use header guards for header files //

1. ifndef PATH_TO_FILE_AND_FILE_NAME_
2. define PATH_TO_FILE_AND_FILE_NAME_

                                                                 // new line
                                                                 // new line

// // Group includes of the same library and separate it using a new line // Order your include files from low level to higher. // 1. libstd C headers: <printf.h>, <file.h>, <math.h> // 2. libstd C++ headers: <fstream>, <thread>, <mutex>, <cmath> // 4. Other 3rd party includes: <boost/mutex.hpp>, <Qt/QtCore>, <ros/ros.h>, // <pcl/pcl.h> // 4. Local includes: <cogniteam/project_name3/SomeClass.h> //

1. include <printf.h>

                                                                 // new line

1. include <iostream>
2. include <fstream>
3. include <mutex>

                                                                 // new line

1. include <boost/bind.hpp>
2. include <boost/thread.hpp>
3. include <boost/thread/mutex.hpp>
4. include <boost/asio.hpp>
5. include <boost/asio/serial_port.hpp>
6. include <boost/system/error_code.hpp>

                                                                 // new line

1. include <ros/ros.h>
2. include <std_msgs/String.h>
3. include <ackermann_msgs/AckermannDriveStamped.h>

                                                                 // new line

1. include <cogniteam/AwesomeClass.h>
2. include <cogniteam/project_name3/JustSomeClass.h>

                                                                 // new line
                                                                 // new line

// // Always wrap your code with a namespace // namespace cogniteam { namespace project_name {

                                                                 // new line
                                                                 // new line

// Include other namespaces using namespace std; using namespace cogniteam::project_name2;

                                                                 // new line
                                                                 // new line

/**

* Custom color for...
*/

enum class CogniColor {

   Red = 1, 
   Blue = 2,
   Green

};

                                                                 // new line
                                                                 // new line

/**

* High level description of class purposes 
* @note Comment using Doxygen's 'Javadoc style' format
* @url http://www.doxygen.nl/manual/docblocks.html
*/

class CogniteamClass : public CogniteamBaseClass {

                                                                                  // Use separate public block for constructors and descructor

public:

   /**
    * Construct a new Cogniteam Class object
    */

CogniteamClass();

   /**
    * Construct a new Cogniteam Class object
    * @param obj1 
    */

CogniteamClass(const SomeClass& obj1);

   /**
    * Copy constructor
    * @note Don't forget to implement copy constructor & copy assignment operator
    *       if you have pointers in your class
    * @param obj1 
    */

CogniteamClass(const CogniteamClass& obj1);

   /**
    * Destroys the Cogniteam Class object
    * @note Always declare virtual desctrutor in your classes
    */

virtual ~CogniteamClass();

public:

   /**
    * Public type alias for convenient
    */
   using Ptr = shared_ptr<CogniteamClass>;

   using ConstPtr = shared_ptr<CogniteamClass const>;

public:

   //
   // Public member methods
   // NO PUBLIC VARIABLE ALLOWED - USE GETTERS AND SETTERS
   //
   // Getter & Setter example for member variable object_:
   //

   /**
    * Set the Var object
    * @note inline setters & getters
    * @note Use const methods for getters
    * @note Setters and getters must be as short as possible, ideally, 
    *       one copy assignment and one return: 
    * @param var 
    * @return int 
    */
   inline void setObject(Object& object) {
       object_ = object;
   }
   
   /**
    * Gets the Object object
    * @return Object 
    */
   inline Object getObject() const {
       return object_;
   }

   /**
    * Use prefix T for template parameters (MessageT, ServiceT, PacketT...)
    * @tparam ObjectT 
    * @param object 
    */
   template <typename ObjectT>
   void templateMethod(const ObjectT& object) {
       // ...
   }

protected:

   //
   // Protected member methods
   //

   /**
    * Protected method, visible by this and derived classes
    * @return int 
    */
   int protectedMethod();

protected:

   //
   // Protected member variables
   //

   /**
    * Protected member variable, visible by this and derived classes
    */
   int protectedMemberVariable_ = 0;

private:

   //
   // Private member methods
   //

   /**
    * Runs my algorithm 
    * @param param1 First parameter
    * @param param2 Second parameter
    * @param param3 Another parameter
    * @return true If success
    * @return false If failure
    */
   bool runAlgorithm(double param1, double param2, double param3);

   /**
    * Calculates a number such that...
    * @param param1 First param for calculationg
    * @return double Calculation result
    */
   double calculateNumber(double param1) const;

private:

   //
   // Private member methods
   //

   /**
    * Const member example, upper case with underscore, place const's first
    */

const string CONST_MEMBER_STRING = "monitor_red";

   /**
    * Private variable, visible by this class only
    */

Object object_;

};

                                                                 // new line
                                                                 // new line

} /* namespace project_name */ } /* namespace cogniteam */

                                                                 // new line
                                                                 // new line

1. endif /* PATH_TO_FILE_AND_FILE_NAME_ */

                                                                 // new line

</syntaxhighlight>

Source file

<syntaxhighlight lang="C++"> /*

* CogniteamClass.cpp
* 
*  Created on: Jan 1, 2031
*      Author: John Doe <johndoe@cogniteam.com>
*
*
* Cogniteam LTD CONFIDENTIAL
*
* Unpublished Copyright (c) 2010-2020 Cogniteam,        All Rights Reserved.
*
* NOTICE:  All information contained  herein  is,  and  remains the property
* of Cogniteam.   The   intellectual   and   technical   concepts  contained
* herein are proprietary to Cogniteam and may  be  covered  by  Israeli  and
* Foreign Patents, patents in process,  and  are  protected  by trade secret
* or copyright law. Dissemination of  this  information  or  reproduction of
* this material is strictly forbidden unless  prior  written  permission  is
* obtained  from  Cogniteam.  Access  to  the  source  code contained herein
* is hereby   forbidden   to   anyone  except  current  Cogniteam employees,
* managers   or   contractors   who   have   executed   Confidentiality  and
* Non-disclosure    agreements    explicitly    covering     such     access
*
* The copyright notice  above  does  not  evidence  any  actual  or intended
* publication  or  disclosure    of    this  source  code,   which  includes
* information that is confidential  and/or  proprietary,  and  is  a   trade
* secret, of   Cogniteam.    ANY REPRODUCTION,  MODIFICATION,  DISTRIBUTION,
* PUBLIC   PERFORMANCE,  OR  PUBLIC  DISPLAY  OF  OR  THROUGH USE   OF  THIS
* SOURCE  CODE   WITHOUT   THE  EXPRESS  WRITTEN  CONSENT  OF  Cogniteam  IS
* STRICTLY PROHIBITED, AND IN VIOLATION OF APPLICABLE LAWS AND INTERNATIONAL
* TREATIES.  THE RECEIPT OR POSSESSION OF  THIS SOURCE  CODE  AND/OR RELATED
* INFORMATION DOES  NOT CONVEY OR IMPLY ANY RIGHTS  TO  REPRODUCE,  DISCLOSE
* OR  DISTRIBUTE ITS CONTENTS, OR TO  MANUFACTURE,  USE,  OR  SELL  ANYTHING
* THAT      IT     MAY     DESCRIBE,     IN     WHOLE     OR     IN     PART
*
*/
                        // Maximum 80 characters per line        // new line  
                                                                 // new line

1. include <cogniteam/CogniteamClass.h>

                                                                 // new line
                                                                 // new line

// // Always wrap your code with a namespace // namespace cogniteam { namespace project_name {

                                                                 // new line
                                                                 // new line

/**

* Construct a new Cogniteam Class object, more deatils about implementation
* can be added here
*/

CogniteamClass::CogniteamClass()

   : varToInit_(1), 
     varToinit2_(2.0) {
   // 
   // Other initialization...
   //

}

/**

* Construct a new Cogniteam Class object
* @param obj1 
*/

CogniteamClass::CogniteamClass(const SomeClass& obj1) {

}

/**

* Copy constructor
* @note Don't forget to implement copy constructor & copy assignment operator
*       if you have pointers in your class
* @param obj1 
*/

CogniteamClass::CogniteamClass(const CogniteamClass& obj1) {

}

/**

* Destroys the Cogniteam Class object
* @note Always declare virtual desctrutor in your classes
*/

CogniteamClass::~CogniteamClass() {

}

/**

* Describe the implementation 
* @param param1 First parameter
* @param param2 Second parameter
* @param param3 Another parameter
* @return true If success
* @return false If failure
*/

bool CogniteamClass::runAlgorithm(double param1, double param2, double param3) {

}

/**

* Describe the implementation
* @param param1 First param for calculationg
* @return double Calculation result
*/

double CogniteamClass::calculateNumber(double param1) const {

}

                                                                 // new line
                                                                 // new line

} /* namespace project_name */ } /* namespace cogniteam */

                                                                 // new line

</syntaxhighlight>

Read more

• ROS C++ style guide
• ROS naming convention