Code conventions

From Nasqueron Agora

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)


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


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

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"?>
    <rule ref="vendor/nasqueron/codestyle/CodeSniffer" />


We follow PEP-8.


We follow Rust default style, described at It's mainly a K&R, 1TBS variant.

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




  • Indent with two spaces
  • YAML lists use indented bullets
    - somekey: value
    - otherkey: value


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


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


  • 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


UNIX agnosticism:

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


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


The 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.