BigBang Open source Style Guides

中文版

Catalog

• Introduction
• Issue
• Pull request
• Wiki
• Commit
• Document
• Code

Introduction

This style guide of Bigbang project is aimed at improving the work of contributors. The guide refers to the original code style, Google C++ Style Guide, the communication habit of participants, etc. It includes communication online, coding and commits.

This style guide is licensed under the CC-By 3.0 license.

Issue

Issue is the parts of discussion and task.

• Suggest English or Chinese in the issue.
• The new issue should describe clearly the background(platform, version, etc.), detail(operation, log) of problem or task.
• When task issue is completed and merged into master, the user who merged should comment the merged commit ID and close it.
• When problem issue is repeated, or duplicated, or out-of-date, or converted to another issue, the creator or owner should comment on the related issue ID and close it.

Pull Request

Pull Request(PR) is the only way to contribute code to master.

• English is required in PR.
• Should describe the aim and main content in PR.
  • If for one issue, should mark the issue ID.
  • Could be only heading if it's simple or plain.
  • Complicated bug should describe the reason and fixed the idea in PR or the related issue.
  • If it's a feature, add a new development document in the doc folder of the repo, and comment the document link.
• The code reviewer of PR should contain the related developer(default in Github). If it's a complicated PR, recommend that at least two reviewers.
• Comment any question in review, and creator resolve it. Don't merge if the following happened:
  • Description is not consistent with code.
  • There is any code beyond description.
  • Code style does not comply with Code Style.
  • There is an ambiguous or meaningless commit.
• Recommend using git merge rebase or git pull -r when synchronizing from master to develop branch.

Wiki

Wiki is a window of BigBang project content except for development documents.

• Modifying the wiki is handled by the core development team.
• English is required in PR, and Chinese is optional.
• If any collaborator will change wiki, fork and modify, and then create an issue.

Commit

Developer should check out a new branch to develop. There are several guides about commit:

• English is required in commits.
• Comment message in commits should describe clearly about the change.
• Recommend that one commit do one thing.
• Using git rebase to modify or squash commits before creating a PR.

Document

Every new feature should be related to one development document. They are in the doc folder of repo.

• English is required in documents, and Chinese is optional.
• There is at least the design of feature in documents.
• If there is any param or API affect other function, mark it in documents.

Code

Launguage

• Must use English in code, comment and file name.

Automated tools

• Formatting code use clang-format version 8.0 or above. Notice: should set only formatting .cpp and .h file. For example in vscode:

   ...
   "[cpp]": {
   "editor.formatOnSave": true
   }
   ...

Header File

• The #define guard，The format of the symbol name should be <PATH>_<FILE>_H, and the <PATH> is relative to src. For example, src/common/template/delegate.h：

  #ifndef COMMON_TEMPLATE_DELEGATE_H
  #define COMMON_TEMPLATE_DELEGATE_H
  ...
  #endif // COMMON_TEMPLATE_DELEGATE_H
  

• Only put inline function, template and declaration in .h file, and others in .cpp.

Variable

• Variable name begins with lower-case letter, and uses camel-case naming.
• Integer prefix is n，likeint nCount。
• Floating prefix is f，likefloat fAmount。
• String prefix is str，likestring strKey。
• vector prefix is vec，likevector<string> vecCmd。
• map prefix is map，likemap<string, string> mapCookie。
• String stream prefix is ss，likeboost::asio::streambuf ssRecv。IO stream prefix is io，likeiostream ioRead。
• Read-write lock prefix is rw，likeCBlockheadRWAccess rwAccess。
• Function object prefix is fn，likeCompltFunc fnComplt。
• Class object no prefix.

Function

• Function name begins with upper-case letter, and uses camel-case naming.
• Input parameter of function should be modified by const.
• If the number of function parameters is too large, the structure should be considered instead.

Class

• Class name begins with C，and uses camel-case naming. Like CTemplateDelegate。
• Provide move constructor and move assignment operator in class as far as possible.

Pointer

• If the pointer is shared by multiple threads or difficult to control the lifetime, use smart pointer instead.
• Null pointer use nullptr.

Template

• Template metaprogramming is not encouraged, unless developer is fully aware of the effect.

auto

• Without affecting readability, could use auto to avoid tedious type name.

Boost

• Prioritize the C++ standard libraries, and then Boost libraries for third part. Reinventing the wheel is not encouraged.
• Use only approved libraries in Boost.

Namespace

• Don't use using namespace in header files.
• Recommand that define an alias of the long namespace name in cpp files by using.
• Recommand static or unnamed namespace to declare the visibility of variables and functions in cpp files.

Comment

• In the top of every source, comment a copyright like others.
• Should comment the class and functions in header files. For historical reasons, this is suspended. Comment style of doxygen will be used.
• Should comment the complex algorithm and logic.
• Should comment for the defination of enum value.

File

• Filenames should be all lowercase and underscores _.
• The suffix of header files is .h.
• The suffix of cpp files is .cpp.
• The suffix of documents is .md.

Platform

• BigBang supports 64-bit platform, include Linux、MacOS、Windows.
• If code depends on specific platform, use the following macros:
  • Linux __linux__。
  • MacOS __APPLE__。
  • Windows __WIN64__。
• The c++ compiler must support __uint128_t.