Style Guide Survey

[Apolo151]

This is the style guide for languages used in RA, RAM, and RI repositories.

Languages: Python, Javascript, C++, CMAKE

This guide is heavily based on the ROS2 (Humble) Coding Style Guide

Python

• Use the PEP8 guidelines for code formatting
  • changes:
    • Maximum Line Length = 88
• Use the PEP257 guidelines for docstrings formatting

---

• Enforce using
  • Linter: flake8,
  • Formatter: black
  • Docstrings validation: pydocstyle

C++

• Use the Google C++ Style Guide with the modifications stated in the ROS2 Style Guide

---

• Enforce using ament_cpplint and ament_uncrustify

CMAKE

• Use the style guide defined by the ROS2 style guide

Summary

• Use lowercase command names (find_package, not FIND_PACKAGE).
• Use snake_case identifiers (variables, functions, macros).
• Use empty else() and end...() commands.
• No whitespace before (‘s.
• Use two spaces of indentation, do not use tabs.
• Do not use aligned indentation for parameters of multi-line macro invocations. Use two spaces only.
• Prefer functions with set(PARENT_SCOPE) to macros.
• When using macros prefix local variables with _ or a reasonable prefix.

---

• Enforce using ament_lint_cmake

Javascript

• Use the recommended ESLint configuration as base, with extra plugins for specific frameworks or tools
  • Example extensions:
    • react for jsx components linting
    • json for JSON linting

---

• Enforce using
  • Linter: eslint
  • Formatter: prettier

Base ESLint Config

{
  "extends": ["eslint:recommended", "prettier"],
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  },
  "parserOptions": {
    "ecmaVersion": 12,
    "sourceType": "module"
  },
  "rules": {
    // Add custom rules if needed
  }
}

HTML/CSS

• Use the Google HTML/CSS Style Guide

---

• Enforce using
  • Linters: eslint, stylelint
  • Formatter: prettier

XML

• Use spaces for indentation. No tabs in content.
• Indentation of 2 spaces per level

---

• Enforce using xmllint/ament_xmllint

YAML

• Use spaces for indentation. No tabs in content.
• Indentation of 2 spaces per level
• Use double quotes for all strings

possible full style guide: https://developers.home-assistant.io/docs/documenting/yaml-style-guide/

---

• Enforce using
  • Linter: yamllint
  • Formatter: yamlfmt

How To Setup Your IDE

Python

VSCode

• Install needed packages in your python environment

pip install flake8 flake8-docstrings pydocstyle black

• Install the flake8 linter vscode extension
• Install the black formatter vscode extension
• Add the following to your settings.json file

{
	// ...
	
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter"
    },
    "black-formatter.args": ["--line-length", "88"],
    "flake8.importStrategy": "fromEnvironment",
    "flake8.args": [
        "--max-line-length=88",
        "--extend-ignore=E701,W503,E203",
        "--docstring-convention=pep257"
    ]
    
    // ...

}

• Docstrings
  • consider installing the autoDocString extension to auto generate docstrings

PyCharm

1. Setup Black in PyCharm

• Similar steps to configure flake8 (details TBD)

Javascript - HTML/CSS - YAML

VSCode

• Install the prettier vscode extension

• Install the eslint vscode extension

• add the following .prettierrc file to the source code

{
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf",
  "overrides": [
    {
      "files": ["*.yaml", "*.yml"],
      "options": {
        "singleQuote": false
      }
    }
  ]
}

• Install the needed modules for the project languages

# Common & JS
npm install --save-dev eslint eslint-plugin-prettier eslint-config-prettier 
# HTML
npm install --save-dev @html-eslint/eslint-plugin @html-eslint/parser
# CSS
npm install --save-dev @eslint/css
# YML
npm install --save-dev eslint-plugin-yml

• Add the following .eslintrc.json to the source code

{
  "root": true,
  "env": {
    "browser": true,
    "node": true,
    "es2021": true
  },
  "parserOptions": {
    "ecmaVersion": 2021,
    "sourceType": "module"
  },
  "extends": [
    "eslint:recommended",
    "plugin:prettier/recommended"
  ],
  "plugins": ["prettier", "@html-eslint", "yml"],
  "overrides": [
    // {
    //   "files": ["*.ts", "*.tsx"],
    //   "parser": "@typescript-eslint/parser"
    // },
    {
      "files": ["**/*.html"],
      "parser": "@html-eslint/parser"
    },
    {
      "files": ["*.css", "*.scss"]
    },
    {
      "files": ["*.yml", "*.yaml"],
      "extends": ["plugin:yml/recommended"]
    }
  ],
  "rules": {
    "indent": ["error", 2],
    "quotes": ["error", "single"],
    "semi": ["error", "always"]
    // "@typescript-eslint/no-unused-vars": "warn"
  }
}

XML

VSCode

• install the RedHat XML Extenstion

C++

VSCode

• Install the C/C++ Extension Pack
• In the Settings, search for C_Cpp.clang_format_fallbackStyle option and update its value to Google

CMAKE

[pariaspe]

Fully agree, ROS 2 coding style is a great example to follow as many developers do

[miferco97]

Nice work! For C++ I should also recommend using -Wall -Werror -pedantic as compilation flags within the CMake. Consider also take an eye on https://github.com/ament/ament_lint/blob/rolling/ament_cmake_lint_cmake/doc/index.rst

[Apolo151]

Thanks.
I have updated the guide with extra languages (including CMAKE).

I think creating a separate guide or section titled ROS2 Package Setup Guide would be a good idea.
It would include stuff like:

• specific c++ compiler flag
• how to setup required linting and testing in CMAKE
• other agreed on best practices for ROS2 packages

[dpascualhe]

Great job 👍 I'm totally onboard.