Turn the guidelines into a tested style standard

[MarcoDotIO]

Summary

Rebuilds the 2017 guidelines into a tested style standard for the lab's six languages: C and C++; Python; JavaScript and TypeScript; Swift; Kotlin; C# and Unity. Every config is copy-ready and is proven by a check script. Written for people and for coding agents.

What's in it

• docs/: one guide per language. Each covers:

  • the style guide the lab follows;
  • naming and layout;
  • the formatter and linter;
  • editor setup;
  • how to adopt the config;
  • a CI snippet and common mistakes.

  Plus pages for:

  • Git and GitHub (Chris Beams' seven commit rules kept);
  • documentation;
  • AI-assisted development (Claude Code and Codex);
  • ROS 2 packages;
  • hardware and firmware;
  • other languages.

• configs/:

  • .editorconfig;
  • clang-format (the ROS 2 ament_clang_format config) and clang-tidy;
  • swift-format and SwiftLint (set up so they don't conflict);
  • ktlint and detekt;
  • C# analyzers;
  • Ruff and mypy;
  • ESLint, Prettier and tsconfig;
  • markdownlint.

• examples/ and scripts/check-configs.sh: each config must pass its good samples and reject its bad/ samples. That is 28 checks, run with only Docker, and configs.yml runs the same checks in CI.

• templates/: README and AGENTS.md templates for lab project repositories.

• AGENTS.md and CLAUDE.md, docs CI, the brand header and social preview.

• License: MIT. The repository had none, so people can copy the configs freely.

For the reviewer

Style decisions, each explained on its page:

• Private C# fields use _camelCase, not Unity's m_ prefix.
• Kotlin uses ktlint's android_studio style.
• Swift uses 4-space indents and 120 columns.
• Python uses 99 columns, matching ament, with Google docstrings.
• Branches are named type/description.
• The wiring colors in docs/hardware.md are a proposed lab convention.

Also:

• ROS 2 C++ packages: exclude ament_cmake_uncrustify and use ament_cmake_clang_format. Testing showed the two can't both pass.
• Placeholders to fill, listed under "Open items" in AGENTS.md:
  • the review turnaround time;
  • the data storage location;
  • the security-incident contact;
  • the parts-ordering and printer-booking processes.

How it was checked

• scripts/check-configs.sh: 28 of 28 pass, and each linter rejects its bad samples. It was run twice, once by me on a separate run.
• In ROS 2 Jazzy, colcon build and colcon test pass 30 tests, including cpplint, cppcheck, flake8 and pep257.
• brand_check.py: 0 errors. markdownlint: 0 issues. lychee: 0 errors. actionlint and shellcheck are clean.
• Not run: Unity itself (the C# samples compile against UnityEngine stand-ins), and whether Unity 6 honors .editorconfig severities. The docs say how to check the latter.

After merge

• The stale develop branch is fully merged into master and can be deleted.
• Upload .github/assets/social-preview.png under Settings → Social preview.

Related PRs: .github · about · getting-started-atr-lab · all-things-ros2

🤖 Generated with Claude Code