- 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)
The following conventions are used:
- K&R, 1TBS variant, including for functions
- 4 spaces as indent
- The keywords
nullmust 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"?> <ruleset> <rule ref="vendor/nasqueron/codestyle/CodeSniffer" /> <file>.</file> <exclude-pattern>\.git/</exclude-pattern> <exclude-pattern>vendor/</exclude-pattern> </ruleset>
We follow PEP-8.
We follow 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.
- Indent with two spaces
- YAML lists use indented bullets
id: method: - 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.
- Don't assume absolute path, use
#!/usr/bin/env bashand 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
- 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
- Test your makefile against BSD make, and document in README.md 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 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.