Code conventions

All languages

• Don't use more complicated constructs like ternary operators
• Keep functions short and simple.
• Define explicitly methods visibility, as several languages have different default values (e.g. private for C# class members, public for PHP methods)
• Comments to document a method are written at the singular 3rd person (we seem to have moved to infinitive recently, we need to take a decision here)

C

If you use ClangFormat, a .clang-format file is available.

JavaScript

The following conventions are used:

• K&R, 1TBS variant, including for functions
• 4 spaces as indent
• Use modern JavaScript idioms like const and let instead of var
• Consider to use async code for events-driven development, especially for servers

PHP

The following conventions are used:

• K&R, 1TBS variant, including for functions
• 4 spaces as indent
• The keywords true, false and null must be in lower case.
• Arrays use short syntax
• Array elements ends with a comma
• Functions, methods and class names use camel case

If you use PhpStorm or another JetBrains IDE, you can import JetBrains/php-codestyle.xml from the codestyle repository as a code style (Settings or Default Settings > Editor > Code Style > PHP > click on the wheel icon > Import Scheme > Intellij IDEA codestyle XML).

If you want to lint a project with phpcs, you can require the Composer package nasqueron/codestyle and use the following phpcs.xml standard file:

<?xml version="1.0"?>
<ruleset>
    <rule ref="vendor/nasqueron/codestyle/CodeSniffer" />
    <file>.</file>
    <exclude-pattern>\.git/</exclude-pattern>
    <exclude-pattern>vendor/</exclude-pattern>
</ruleset>

Python

2023. We follow black style, so use black utility (pip install black). As such, you need to configure Flake8 to ignore rule E203.

2015. We follow PEP-8.

Rust

2023. Automated codestyle (black in Python, clang-format in Rust) seems preferable. As such, a style compatible with rustfmt is needed to be able to format using cargo fmt. You can add to your project rust/rustfmt.toml in codestyle to configure it.

2015. We followed "Rust default style", described at https://aturon.github.io/. It's mainly a K&R, 1TBS variant.

Use trailing comma for elements in every struct/impl/etc.

Salt

Style

Whitespaces:

• Indent with two spaces
• YAML lists use indented bullets

id:
  method:
    - somekey: value
    - otherkey: value

Tips

Files provisioned

• When you ask to download a file remotely, you need a source hash, pick SHA256 as algo
• Each file provisioned from the Salt repository must contains an header explaining the fact, with the full path in the rOPS repo

BSD and Linux distros compatible states

• populate the map.jinja file with OS logic (e.g. `dirs` for /etc vs /usr/local/etc)
• when you've a specific set of tasks to do for one OS/distro, it's acceptable to enclose it in a state by an if block

Vocabulary

Domain names

To refer to the fully qualified domain name sub.domain.tld, use fqdn. To split the domains in part, use domain and subdomain. This is important to understand a state without having to refer to the associated pillar to disambig domain.

Shell scripts

UNIX agnosticism:

• Don't assume absolute path, use #!/usr/bin/env bash and not #!/bin/bash (it could be elsewhere on BSD or Solaris)
• Use `sh` as must as possible, try to avoid bash, document exceptions rationale in your commits

Whitespaces:

• One whitespace line between shebang and actual content
• Indent with tabulations

File names:

• We use hyphens (-) as separators, not underscores or camelcase.
• Filename should start by a verb if it performs an action
• Don't use .sh extensions (sometimes you'll see them on Phabricator pastes' titles, but it has been added there, so Phab knows shell syntax highlighting should be used)
  • Tip. You can use .sh in src/ to help linters, but then provide a Makefile to install it under correct name without extension

Makefile

UNIX agnosticism:

• Test your makefile against BSD make, and document in README.md to use GNU Makefile (gmake) when it's not convenient to keep compatibility

Presentation:

• Create a block with the general targets, then sections with your targets organized by categories/goals/parts

Tip:

• It's possible to provision BSDmakefile and GNUmakefile when UNIX agnosticism doesn't work.

Structured data formats (YAML, JSON, XML)

The number of spaces depend if the format is usually heavily hierarchized or not:

• 2 spaces for JSON and YAML
• 4 spaces for XML, TOML and other configuration files

Utilities

The https://github.com/nasqueron/codestyle repository contains resource to help to respect code convention, like a phpcs ruleset, a configuration ready for PhpStorm, IntelliJ and other JetBrains editors, or a clang-format configuration file.

Troubleshoot

Fix indent issues

The expand utility converts tabs into spaces, while unexpand convert spaces into tabs.

Switch a file from tab indent to 4 spaces indent:

   $ expand -t 4 foo.sh > a
   $ cat a > foo.sh
   $ rm a

(Avoid mv for shell scripts as your foo.sh has probably a 755 chmod, and a will probably have a 644 chmod, assuming 022 as umask)

Switch a file indent with 2 spaces to 4 spaces:

   $ unexpand -t 2 JetBrains/php-codestyle.xml > a
   $ expand -t 4 a > JetBrains/php-codestyle.xml

This last technique can be used in batch with this reindent script:

   $ git ls-files | xargs -n1 reindent 2 4