Subsections of Coding Guideline

C++ Coding Guideline

This page contains data about how we refactor, format and write our code with C++.

We decided not to invent wheel again and again so that, we’re using every clang tools as base tool in our projects. Firstly, we’ll start with how we format our code.

  • There’re two major tool(IDE or Editor) that we use currently: VS Code and Eclipse. You might know that VS Code has internal clang format support. Only thing that you should do is adding your clang-format file into project folder(Name of file must be like this: .clang-format ). For Eclipse, you need a simple plugin. You can follow this guideline to use with it.

  • As we said before, no need to reinvent the wheel. There are generally accepted coding standards. LLVM, Google, Mozilla and list go on. We decided to continue with LLVM but it needs some fixes.

  • At BISS, we’re using this formatter for C/C++ Project. Please don’t alter any line of this file without noticing Process Design team.

    • You can also check this interactive web tool in order to see what LLVM applies on your code. Just select BasedOnType as LLVM.

C# Coding Guideline

C# is a general-purpose, modern and object-oriented programming language pronounced as “C Sharp”. It was developed by Microsoft led by Anders Hejlsberg and his team within the .NET initiative and was approved by the European Computer Manufacturers Association (ECMA) and International Standards Organization (ISO). C# is among the languages for Common Language Infrastructure. C# is a lot similar to Java syntactically and is easy for users who have knowledge of C, C++, or Java.

Below are some of the best practices which all the .Net Developers should follow:

  • Class and Method names should always be in Pascal Case
public class Employee
{
    public Employee GetDetails()
    {
        //...
    }
    public double GetBonus()
    {
        //...
    }
}
  • Method argument and Local variables should always be in Camel Case
public class Employee
{
    public void PrintDetails(int employeeId, String firstName)
    {
        int totalSalary = 2000;
        // ...
    }
}
  • Avoid the use of underscore while naming identifiers
// Correct
int employeeId;
string employeeName;
bool isActive;


// Avoid
Int32 employee_id;
String employee_name;
Boolean is_active;
  • Always prefix an interface with letter I.
// Correct
public interface IEmployee
{
}
public interface IShape
{
}
public interface IAnimal
{
}

// Avoid
public interface Employee
{
}
public interface Shape
{
}
public interface Animal
{
}
  • For better code indentation and readability always align the curly braces vertically.
// Correct
class Employee
{
    static void PrintDetails()
    {
    }
}


// Avoid
class Employee
    {
    static void PrintDetails()
    {
      }
}
  • Always use the using keyword when working with disposable types. It automatically disposes the object when program flow leaves the scope.
using(var conn = new SqlConnection(connectionString))
{
    // use the connection and the stream
    using (var dr = cmd.ExecuteReader())
    {
     //
    }
}
  • Always declare the variables as close as possible to their use.
// Correct
String firstName = "Shubham";
Console.WriteLine(firstName);
//--------------------------
ExampleFunction();
AnotherFunction();
AnotherBusinessLogic();


// Avoid
String firstName = "Shubham";
ExampleFunction();
AnotherFunction();
AnotherBusinessLogic();
Console.WriteLine(firstName);
  • Always declare the properties as private so as to achieve Encapsulation and ensure data hiding.
// Correct
private int employeeId { get; set; }

// Avoid
public int employeeId { get; set; }
  • Always seperate the methods, different sections of program by one space.
// Correct
class Employee
{
	private int employeeId { get; set; }

	public void PrintDetails()
	{
	//------------
	}
}

// Avoid
class Employee
{

	private int employeeId { get; set; }



	public void PrintDetails()
	{
	//------------
	}

}
  • Constants should always be declared in UPPER_CASE.
// Correct
public const int MIN_AGE = 18;
public const int MAX_AGE = 60;

// Avoid
public const int Min_Age = 18;
public const int Max_Age = 60;
  • Use singular names for enums. Exception: bit field enums.
// Correct
public enum Color
{
    Red,
    Green,
    Blue,
    Yellow,
    Magenta,
    Cyan
}

// Exception
[Flags]
public enum Dockings
{
    None = 0,
    Top = 1,
    Right = 2,
    Bottom = 4,
    Left = 8
}

// Avoid
public enum Cars //Plural
{
    Bugatti,
    Ferrari,
    Ford,
    Audi,
    BMW
}
  • Naming Convention Examples
Language element Casing Example
Namespace Pascal System.Drawing
Type parameter Pascal TView
Interface Pascal IBusinessService
Class, struct Pascal AppDomain
Enum Pascal ErrorLevel
Enum member Pascal FatalError
Resource key Pascal SaveButtonTooltipText
Constant field Pascal MaximumItems
Private static readonly field Pascal RedValue
Private field Camel listItem
Non-private field Pascal MainPanel
Property Pascal BackColor
Event Pascal Click
Method Pascal ToString
Local function Pascal FormatText
Parameter Camel typeName
Tuple element names Pascal (string First, string Last) name = ("John", "Doe"); var name = (First: "John", Last: "Doe"); (string First, string Last) GetName() => ("John", "Doe");
Variables declared using tuple syntax Camel (string first, string last) = ("John", "Doe"); var (first, last) = ("John", "Doe");
Local variable Camel listOfValues

Note: in case of ambiguity, the rule higher in the table wins.

  • Use string interpolation to concatenate short strings, as shown in the following code.
string displayName = $"{nameList[n].LastName}, {nameList[n].FirstName}";
  • To append strings in loops, especially when you are working with large amounts of text, use a StringBuilder object.
var phrase = "lalalalalalalalalalalalalalalalalalalalalalalalalalalalalala";
var manyPhrases = new StringBuilder();
for (var i = 0; i < 10000; i++)
{
    manyPhrases.Append(phrase);
}
//Console.WriteLine("tra" + manyPhrases);
  • Lambda Expression
  public Form2()
  {
      // You can use a lambda expression to define an event handler.
      this.Click += (s, e) =>
          {
              MessageBox.Show(
                  ((MouseEventArgs)e).Location.ToString());
          };
  }
  • Linq Queries
var localDistributors =
    from customer in customers
    join distributor in distributors on customer.City equals distributor.City
    select new { Customer = customer, Distributor = distributor };

C Coding Guideline

This document is prepared to help developers about how to write the code. It contains different types of code language rules. These rules make writing, maintaining, reviewing the code easier. Also some rules increase portability, …

Horizontal Spacing

Tab usage with space

In most projects, we are using number of spaces instead of using the tab character(\t). Most cases 4 spaces could be use for tab key. This can be set from settings of most IDE’s.

Unary Operators

The unary operators are written with no space between the operator and the operand.

!value 
~bits 
++i 
j-- 
(CPU_INT32U)x 
*ptr 
&x 
sizeof(x)

Binary Operators

The binary operators (and the ternary operator) are written with at least on space between the operator and operands.

c1 = c2; 
x + y 
i += 2; 
n > 0 ? n : -n 
a < b 
c >= 2

Expressions

Expressions within parentheses are written with no space after the opening parenthesis and no space before the closing parenthesis.

x = (a + b) * c;

if and if-else statements

if(x < y)
{
    return -1;
}
else if(x > y)
{
    return 1;
}
else
{
    return 0;
}

while, do-while and for loops

while(condition)
{
}

do
{
} while(condition);

for(int i = 0, j = argc; i < argc; i++, j--)
{
}

switch-case statements

switch(number)
{
case RED:
    return GREEN;
case GREEN:
    return BLUE;
case BLUE:
    return RED;
default:
    return BLACK;
}

Naming Convention

In this section, there are some naming convention rules for C language.

These rules can be applied to:

  • Public and local functions
  • Typedef struct and enumeration
  • Public and local variables

Public and Local Functions

Naming convention of functions is important because if there is a good naming for functions, it would be easy to read the code.

Public Functions

Public functions can be called from another files. So it is better to put some prefix before function name:

Example:

void network_stackMgmt(int code);
bool uartIO_txEnable(void);

Local Functions

Local functions can be called only from inside the file that the function is written. So there is no need to put a prefix before function name:

static void clearBuffer(void);
static bool getState(int index);

Typedef Struct and Enumeration

Naming convention of typedef structures and enumerations is important because if there is a good naming, it would be easy to read the code.

Struct

If there is a good naming for the structure definition, it would be easy to read the code.

struct s_deviceManagerRing {
    uint8 link;
    char mac[18];
};

Typedef Struct

If there is a good naming for the typedef structure definition, it would be easy to read the code.

typedef struct {
    uint64_t mac;
    char ipServer[48];
    uint16_t portServer;
    uint16_t portClient;
} ts_gsmNet;

Enumeration

İf there is a good naming for the enumeration definition, it would be easy to read the code.

enum e_deviceManagerStates {
    E_DEVICE_MANAGER_INIT = 0,
    E_DEVICE_MANAGER_START,
    E_DEVICE_MANAGER_STOP,
};

Typedef Enumeration

If there is a good naming for the typedef enumeration definition, it would be easy to read the code.

typedef enum {
    E_DIO_E_INPUT_1 = 0,
} te_dioInputs;

Public and Local Variables

Naming convention of variables is important because if there is a good naming for variables, it would be easy to read the code.

Public Variables

Public variables can be used from another files. So it is important to have a prefix before the variable name like this:

char uartIO_respReady[6] = "READY";
char lon_respSet[6] = "SET\r\n";

Local Variables

Local variables can be used from only the file that they are written inside. So it is not important to have a prefix before the variable name.

static bool up;
static uint64_t local;
static uint8_t button;

File Content

It is better to have sections inside the file in every coding language. In this section there are some rules about file content.

File content should be separated with some comment blocks. So this way, it would be easy to find what we are looking for in the file content.

To get a documentation from the comments, Doxygen format is used for comments.

Doxygen Comment Blocks

This section is prepared to give some information about doxygen comment blocks and how to write them.

Function Documentation

Here is one example:

/**
* \brief Initializes the UART handle.
* \param config UART configuration string (ex. "COM1:115200,N,8,1")
* \return Returns a handle to the newly opened UART
*/
UART_HandleTypeDef *uartOpen(char *config)
{
    ...
}

Variable Documentation

Here is one example:

static uint8 mode[2]; /**< Uart mode * /

Define Documentation

Here is one example:

/* UART configuration */
#define UARTIO_EVEN     FALSE /**< Even parity */
#define UARTIO_PARITY   FALSE /**< Parity enabled */
#define UARTIO_WORDLEN  E_AHI_UART_WORD_LEN_8 /**< Word length */
#define UARTIO_ONESTOP  TRUE /**< One stop bit */

File Heading

A comment block must be placed at the beginning of each source code file (both code and header files) containing;

  • Filename
  • Brief(short description)
  • Details(detailed description)
  • Remarks(additional remarks)

Here is one example comment block:

/**
 * \file        Filename
 * \brief       A brief description, one sentence, one line.
 * \details     A detailed description of the file scope, it can span over
 *              multiple lines, can be omitted.
 * \remarks     Additional remarks.
 */

File Layout

Both source and header files must be divided by sections:

  • INCLUDE FILES
  • MACRO DEFINITIONS
  • LOCAL DATA TYPES
  • LOCAL CONSTANTS
  • VARIABLES
  • LOCAL FUNCTION PROTOTYPES
  • PUBLIC FUNCTION
  • LOCAL FUNCTION

Even if the section is empty, it’s comment block must be added to the file:

/*----------------------------< Section Name >--------------------------*/

Include Section

The INCLUDE FILES section should include all necessary header files.

/*------------------------------< Includes >-----------------------------*/
#include <iostream>
#include <thread>

Macro Definitions Section

The MACRO DEFINITIONS section should include all necessary macro defines.

/*--------------------------< Macro Definitions >-----------------------*/
#ifndef TRACE_APP
#define TRACE_APP	TRUE
#endif

Local Constants Section

The LOCAL CONSTANTS section should include all necessary constant variables.

/*--------------------------< Constants >-------------------------------*/
const uint32 msecCount = 1800;

Local Data Types Section

The LOCAL DATA TYPES section should include all necessary data type definitions.

/*----------------------------< Typedefs >-------------------------------*/
typedef struct
{
    bool rts;			/**< Current RTS setting */
    bool cts;			/**< Current CTS setting */
} ts_uart;

Local Variables Section

The LOCAL VARIABLES section should include all necessary local(static) variables.

/*---------------------------< Variables >------------------------------*/
static uint8 uart = APP_UART_0;

Local Function Prototypes Section

The LOCAL FUNCTION PROTOTYPES section should include all necessary local(static) function prototypes.

/*-------------------------< Prototypes >-----------------------------*/
static void delayMsec(uint32 period);

Public Function Section

The PUBLIC FUNCTION section should include all necessary public function declarations.

/*---------------------------< Public Function >------------------------*/
void dio_outputInitialise(void)
{
    ...
}

Local Functions Section

The LOCAL FUNCTION section should include all necessary local(static) function declarations.

/*-------------------------< Private Function >--------------------------*/
static void initialiseApp(void)
{
    ...
}

Abbreviations

Please refer to here to see abbreviations.

Subsections of Templates

Changelog Template

Here you can find a template for project Changelog below.

Legend:

  • “[+]”: New feature
  • “[#]”: Bug fix
  • “[~]”: Refactoring, general changes or others that doesn’t fit first two
# Changelog

## [Unreleased]

- [+] "Frequently Asked Questions" section.
- [~] Remove empty sections from CHANGELOG, they occupy too much space and
  create too much noise in the file. People will have to assume that the
  missing sections were intentionally left out because they contained no
  notable changes.

## [v4.0.0] - 2023-06-20

- [+] "Why keep a changelog?" section.
- [+] New "Guiding Principles" sub-section to "How do I make a changelog?".
- [#] Improve "Commit log diffs" sub-section to further argument against
  them.
- [#] Fix typos in Brazilian Portuguese translation.
- [~] Clarified the section on "Is there a standard change log format?".

## [v3.4.1] - 2022-06-20
- [#] Merge "Why can’t people just use a git log diff?" with "Commit log
  diffs"
- [#] Fix typos in Simplified Chinese and Traditional Chinese translations.
- [+] "Who needs a changelog?" section.
- [+] "How do I make a changelog?" section.
- [~] Remove empty sections from CHANGELOG, they occupy too much space and
  create too much noise in the file. People will have to assume that the
  missing sections were intentionally left out because they contained no
  notable changes.
- [~] Clarified the section on "Is there a standard change log format?".

ReadME Template

Here you can find a template for project ReadMe below.

## Your Coolest Project Name

Basic information about your cool project goes here.

*Assume your project is an React project forked from `create-react-app`*

#### Development Environment

Give information about how to prepare a development environment for your coolest project.

*Example:*
*This project uses `nodejs 14.15.5` with `npm 7.5.3`*

*After cloning this project and installing nodejs In the project directory, you have to run:*

*`npm install`*

*and your development environment is ready.*

If you are using a tool formatting such as prettier, clang etc. don't forget to give information about this also.



#### Available Scripts

After preparing development environment give information for available scripts. 

***Examples:***

*In the project directory, you can run:*

### *`npm start`*

*Runs the app in the development mode.<br  />*

*Open [http://localhost:3000](http://localhost:3000) to view it in the browser.*

*The page will reload if you make edits.<br  />*

*You will also see any lint errors in the console.*

### *`npm test`*

*Launches the test runner in the interactive watch mode.<br  />*

*See the section about [running tests](https://facebook.ggithub.io/create-react-app/docs/running-tests) for more information.*

### *`npm run build`*

*Builds the app for production to the `build` folder.<br  />*

*It correctly bundles React in production mode and optimizes the build for the best performance.*

*The build is minified and the filenames include the hashes.<br  />*

*Your app is ready to be deployed!*

### *npm run pretty*

*Format all of your code with our prettier configuration.<br/>*

*You commits are ready to push!*



#### Dependencies

List your cooles project's dependencies as a list in this section, it could be a library, other microservice etc. 

#### Additional Sections

Add sections for developer guideline, third party library usage examples, how to deploy manually, project's configuration, etc.  

*If anything is need to be known, go on add a new section for that knowledge!* 

#### Contributors

Mention the contributors

 

Finally, motivate the developer who will be working the coolest project with this PS:

*Happy Hacking!*

clang Formatter

You can find the clang formatter that is being used on BISS projects below.


---
BasedOnStyle: LLVM
IndentWidth: '4'
---
Language: Cpp
AlignAfterOpenBracket: Align
AlignConsecutiveAssignments: 'false'
AlignConsecutiveBitFields: 'false'
AlignConsecutiveDeclarations: 'false'
AlignConsecutiveMacros: 'true'
AlignEscapedNewlines: Left
AlignOperands: 'true'
AlignTrailingComments: 'true'
AllowAllArgumentsOnNextLine: 'true'
AllowAllConstructorInitializersOnNextLine: 'true'
AllowAllParametersOfDeclarationOnNextLine: 'true'
AllowShortBlocksOnASingleLine: 'Always'
AllowShortCaseLabelsOnASingleLine: 'false'
AllowShortEnumsOnASingleLine: 'false'
AllowShortFunctionsOnASingleLine: Empty
AllowShortIfStatementsOnASingleLine: Never
AllowShortLambdasOnASingleLine: Empty
AllowShortLoopsOnASingleLine: 'false'
AlwaysBreakAfterReturnType: 'None'
AlwaysBreakBeforeMultilineStrings: 'false'
AlwaysBreakTemplateDeclarations: 'Yes'
BinPackArguments: 'true'
BinPackParameters: 'true'
BreakBeforeBinaryOperators: 'None'
BreakBeforeBraces: Allman
#BreakBeforeConceptDeclarations: 'false'
BreakBeforeTernaryOperators: 'true'
BreakConstructorInitializers: BeforeColon
BreakInheritanceList: BeforeColon
BreakStringLiterals: 'true'
ColumnLimit: '100'
CompactNamespaces: 'false'
ConstructorInitializerAllOnOneLineOrOnePerLine: 'false'
ContinuationIndentWidth: '4'
Cpp11BracedListStyle: 'true'
#EmptyLineBeforeAccessModifier: LogicalBlock
FixNamespaceComments: 'true'
IncludeBlocks: 'Regroup'
#IndentAccessModifiers: 'true'
IndentCaseBlocks: 'false'
IndentCaseLabels: 'true'
IndentExternBlock: 'Indent'
IndentPPDirectives: 'None'
#IndentRequires: 'true'
IndentWrappedFunctionNames: 'true'
MaxEmptyLinesToKeep: '1'
NamespaceIndentation: 'None'
PointerAlignment: Left
ReflowComments: 'true'
SortIncludes: 'true'
SortUsingDeclarations: 'true'
SpaceAfterCStyleCast: 'false'
SpaceAfterLogicalNot: 'false'
SpaceAfterTemplateKeyword: 'false'
#SpaceAroundPointerQualifiers: 'Default'
SpaceBeforeAssignmentOperators: 'true'
#SpaceBeforeCaseColon: 'false'
SpaceBeforeCpp11BracedList: 'false'
SpaceBeforeCtorInitializerColon: 'true'
SpaceBeforeInheritanceColon: 'true'
SpaceBeforeParens: ControlStatements
SpaceBeforeRangeBasedForLoopColon: 'true'
SpaceBeforeSquareBrackets: 'false'
SpaceInEmptyParentheses: 'false'
SpacesBeforeTrailingComments: '2'
SpacesInAngles: 'false'
SpacesInCStyleCastParentheses: 'false'
SpacesInConditionalStatement: 'false'
SpacesInContainerLiterals: 'false'
SpacesInParentheses: 'false'
SpacesInSquareBrackets: 'false'
Standard: c++20
TabWidth: '4'
UseCRLF: 'false'
UseTab: Never
---
Language: Proto
BasedOnStyle: Google
...