code-convention.md

• Feature Name: code-convention
• Start Date: 2021-3-29
• RFC PR: #1 #2

Summary

4Paradigm's coding convention apply to C/CPP, Java, Scala, Python, Yaml, Json, Shell Script.

Motivation

Archive better code quality by:

• Enforce well-known code convention like Google's Style to main programing languages
• Use linter check tools and bootstrap those tools in automatic CICD check

Detailed design

Overview

In summary, imperative languages (C/CPP, Java, Scala, Python), is based on Google's Style Guide if have, with a bit adjustment:

• indent: 4 space
• max line length: 120 character
• name convention: we follow Google's naming convention which is camel case. One thing pointed out here is that for abbreviations, only capitalized the first letter. e.g., Start RPC should name as StartRpc

Concrete style guide can be found:

• Google CPP Style Guide
• Google Java Style Guide
• Google Python Style Guide

Data-Serialization language like yaml/json, should follow:

• indent: 2 space
• max line length: 120 character
• prefer double quote (json excluded)

Suggested linter and formater

By default, appropriate linters should setup in CICD to enforce convention in place like Pull Request. Formater is usually used in local development to quickly resolve some style issues. There is no need to use exactly same tools and configuration, any tools respect overview rules should suffice.

language	linter	linter config	formater	format config
cpp	cpplint	default config	clang-format	.clang-format
java	checkstyle	style.xml	eclipse.jdt	eclipse-formater.xml
scala	scalastyle	scala_style.xml	scalafmt
python	pylint	pylintrc	yapf	default with google style
yaml/json	-	-	prettier	prettierrc
shell	shellcheck	default	shfmt	default with indednt = 4

formater do not always solve lint error, dig hard to the lint rule.

Cpp

• linter: cpplint, with linelength=120
• formater: clang-format and .clang-format based on Google style config

java

• linter: checkstyle
  • use template google_checks.xml
  • checkstyle maven plugin: https://maven.apache.org/plugins/maven-checkstyle-plugin/
• formater: spotless provide eclipse.jdt integration.

Scala

• linter: scalastyle with maven plugin
• formater: scalafmt with spotless

Python

• pylint: based on config provided by google: pylintrc
• yapf: a sample yapf config: style.yapf

Yaml/Json/Xml

• config in prettierrc
  • tabWidth: 2
  • singleQuote: false
  • printWidth: 120

Shell Script

• follow shellcheck rules: https://github.com/koalaman/shellcheck/wiki/Checks
• follow shfmt format rules: https://github.com/mvdan/sh/blob/master/cmd/shfmt/shfmt.1.scd

doxygen

• doxygen comment rules: https://www.doxygen.nl/manual/docblocks.html
• doxygen markdown support: https://www.doxygen.nl/manual/markdown.html
• c++ comment style: https://github.com/4paradigm/HybridSE/discussions/27#discussioncomment-546319
• java/scala comment style: @tobegit3hub
• python comment style: @tobegit3hub