Coding Style

Precedence

The Adblock Plus coding style is based on others. Our rules (both general and language specific) always overrule referenced style guides. The language specific sections overrule the general section.

Consistency

Consistency is most important: Be consistent within functions, files, modules and projects. Making existing code conform with this style guide is fine, but it should happen in dedicated commits, preferably for a whole module or project at once.

General

• Follow the Mozilla Coding Style's general practices and its naming and formatting rules.
• All files should have a license header, but no mode line comments.
• Newline at end of file, otherwise no trailing whitespace.
• Lines can be longer than the limit, if limiting line length would hurt readability in a particular case.
• Opening braces always go on their own line.
• No hungarian notation, no special variable name prefixes or suffixes denoting type or scope. All variable names start with a lower case letter.
• Don't comment code out, delete it.
• Don't add TODO comments, create an issue and reference it in a comment instead.

JavaScript

• Follow the Mozilla Coding Style's JavaScript practices.
• Always use strict mode.
• When splitting overlong expressions into multiple lines the joining binary operators should be left at the end of the line, before the linebreak. This does not apply to member access operators, such as . which should be placed on the following line.
• When an if statement, an else statement or a loop spans over more than one line always enclose it with braces.
• In classes, prefix private functions with a single underscore to make them pseudo-private.
• Don't add any spaces immediately after opening, or before closing, an object or array literal.

Modern JavaScript (where supported)

• Always use block-scoping (let / const), except when sharing global variables between scripts cannot be avoided.
• Use const for constant expressions that could as well have been inlined (e.g. static parameters, imported modules, etc.).
• Use the arrow function syntax when passing anonymous functions that don't require the binding of their own this or arguments variables.
• Use the method definition shorthand syntax when defining methods on an object.
• When iterating over arrays in the canonical order use the new for..of syntax if the loop index isn't required. (Rather than using for(;;) or the forEach() method.)
• Use the Map or Set objects, rather than misusing plain objects, when you need a hash table.
• Run ESLint with the eslint-config-eyeo configuration and fix any warning.

HTML and CSS

• Follow the Google HTML/CSS Style Guide.
• Use double over single quotation marks.
• Don't omit optional HTML tags.
• CSS color values should be specified in hexadecimal where possible.
• CSS shorthand properties usage is optional.
• CSS rule declaration order should follow the WordPress CSS Coding Standards.
• Don't omit the optional leading 0 for decimal numbers.
• CSS declaration blocks with a single selector and a single rule can be written in a single line.
• CSS font weight values should be specified in relative or numerical notation

Python

• Follow PEP-8 and the recommendations in the offical Python documentation.
• Make the code compatible with Python 3.5+.
• Write string literals so that they match the behaviour of ascii(), i.e. use single quotes except to avoid escaping of embedded quotes and use \u escapes for non-ascii characters but don't prefix strings with u. For docstrings, however, follow PEP-257.
• In modules, prefix private functions and variables with a single underscore.
• Use the + operator when concatenating exactly two strings, use the format() method for more complex string formatting, use the join() method when concatenating pre-existing sequences.
• Use tuples for data that have structure, use lists for data that have order.
• Don't override builtins.
• Use list comprehensions or generator expressions instead of calling map() or filter() with a lambda function.
• The preferred way of wrapping long lines is by using Python's implied line continuation inside parentheses, brackets and braces. Long lines can be broken over multiple lines by wrapping expressions in parentheses:
  1. aligning follow up lines with the opening parentheses and putting the closing parentheses at the end of the last line (example), or

         long_object_name.long_method_name(argument1, argument2,
                                           keyword_argument=value)
     
         very_long_variable = ['a list of', 'strings that does not',
                               'fit into', 'one line']
             

  2. breaking the line at the opening parentheses, indenting follow up lines by 4 spaces, and placing the closing parentheses on a separate line that is aligned with the line that contains the opening parentheses (example).

         long_object_name.long_method_name(
             argument1,
             argument2,
             keyword_argument=value,
         )
     
         very_long_variable = [
             'a list of',
             'strings that does not',
             'fit into',
             'one line',
         ]
             

  When breaking lists of items separated by commas (e.g. lists, dicts, argument lists) using the second approach add a comma after the last element. This allows adding and rearranging items without touching unrelated lines.
• Use re.search() instead of re.match() to avoid confusion about implied beginning of the string but not the ending.
• Run flake8 with following extensions and fix all reported errors:
  • flake8-eyeo
  • flake8-docstrings (with D1 ignored)
  • flake8-commas
  • pep8-naming
• Write tests and have them run along flake8 using tox.

Java

• Follow the Mozilla Coding Style's Java practices.
• Imports should be organised consistently per file, we don't use global rules.

C++

• Follow the Mozilla Coding Style's C++ practices.
• Indent namespace bodies.
• Avoid manual memory management: Use references and values when possible, smart pointers when necessary, raw pointers only for weak references.
• Don't use C-style casts unless its exact semantics are required.
• We tend to use anonymous namespaces instead of static.

Objective-C

• Follow Apple's conventions.

Puppet

• Follow the Puppet Style Guide.
• Opening braces don't go on their own line.
• Arrows should not be aligned.