Code conventions: Difference between revisions
No edit summary |
No edit summary |
||
Line 103: | Line 103: | ||
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. | 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. | ||
== Tips == | |||
=== Fix indent issues === | |||
Switch a file from tab indent to 4 spaces indent: | |||
expand -t 4 foo.sh > a | |||
mv a foo.sh | |||
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 | |||
[[Category:Reference]] | [[Category:Reference]] |
Revision as of 22:28, 5 June 2023
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
andlet
instead ofvar
- 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
andnull
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"?>
<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
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.
Tips
Fix indent issues
Switch a file from tab indent to 4 spaces indent:
expand -t 4 foo.sh > a mv a foo.sh
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