By using this site, you agree to have cookies stored on your device, strictly for functional purposes, such as storing your session and preferences.

Dismiss

Update style guide

roundabout,
created on Saturday, 25 May 2024, 08:08:35 (1716624515), received on Wednesday, 31 July 2024, 06:54:48 (1722408888)
Author identity: vlad <vlad.muntoiu@gmail.com>

e43a718c08a37045ff20d5172cea6961e5ea7da0

doc/internal/Contributing.md

@@ -0,0 +1,435 @@

                                
                                
                                
                            
                                
                                    
                                        
                                        Contributing Requirements
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        =========================
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Style Guide
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        -----------
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        This document provides conventions for the coding style used in the Roundabout project.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Rules can be broken -- just try to make the code as readable as you can.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        When something is not covered by this document, refer to [PEP 8](https://peps.python.org/pep-0008/).
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        However, please read this even if you know PEP 8, as it diverges in some places.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ### Code Layout
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        #### Indents and Line Continuation
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Keep lines up to 80 characters long. Use 4 spaces for indentation, per level. Do not use tabs, and do not put trailing whitespace.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        For parentheses, three styles are accepted:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ~~~python
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        # No indent.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        thing = function(arg1, arg2)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        # Hanging indent. Align to the contents, not to the bracket.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        thing = function(arg1, arg2
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                                         arg3, arg4, arg5)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        # Full indent. Here only one argument or variable or whatever is allowed per line.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        # The closing bracket must be at the previous indent level.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        # Any level is allowed, but it must be a multiple of 4.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        thing = function(
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            arg1,
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            arg2,
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            arg3,
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            arg4
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        )
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ~~~
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Collections should read like lists, not tables.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ~~~python
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        fruits = ["apple", "tomato", "pear", "cherry", "plum", "melon", "grape", "aubergine",]
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        fruits = [
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            "apple",
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            "tomato",
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            "pear",
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            "cherry",
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            "plum",
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            "melon",
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            "grape",
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            "aubergine",
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ]
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        # Don't!
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        fruits = [
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            "apple", "tomato", "pear", "cherry",
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            "plum", "melon", "grape", "aubergine",
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ]
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ~~~
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Additionally, for a collection meant to be expanded use a trailing comma.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        For long expressions, begin the line with the operator and align the operand with the indentation level.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        This is not permitted by PEP 8, but it follows mathematics and leads to nicer layouts.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ~~~python
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        population = (population
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                                    + births
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                                    + immigrants
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                                    - deaths
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                                    - emigrants)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ~~~
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        When the hanging indent could be mistaken for a block, add an empty line.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Backslashes are discouraged, but allowed if it is the only way to write your expression. For
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        example:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ~~~python
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        really_long_variable_name_hopefully_yours_wont_be_as_long = \
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            "Really long value."
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ~~~
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        #### Blank Line Rules
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * Two between top-level class or function definitions.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * One between local functions or methods.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * One is allowed to separate related groups and logical sections.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * One at the end of the file.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * One below imports.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        #### Imports
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Imports should be on separate lines. `from`-imports must import all objects on the same line though.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ~~~python
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        import flask
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        import os
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        from models import User, Post
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ~~~
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Imports should be ordered like this:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * `__future__` statements
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * one blank line
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * magic names (`__all__`, `__version__`)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * one blank line
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * library imports
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * library `from`-imports
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * one blank line
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * application imports
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * application `from`-imports
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Wildcard imports are discouraged and prohibited for libraries. However, they are fine if the module
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        defines `__all__`.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        #### Interior Whitespace
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Never insert more than one space around operators and other symbols. Never add spaces just to align lines.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ##### When to use
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * around the lowest priority operators in an expression, comparisons, assignments, and logical operators, as well as the function annotation arrow
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          ~~~python
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Do
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          thing += 10 + 2*thing
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Don't
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          thing+=10+2 * thing
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Acceptable; use your best judgement
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          thing += 10 + 2 * thing
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          ~~~
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * after the colon when defining a single-line clause, or an annotation
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * after commas or semicolons
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * after the comment sign `#`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        #### When to avoid
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * when passing keyword arguments or defining argument defaults, unless they are annotated
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * inside any brackets
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          ~~~python
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Do
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          function(arg1, arg2)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Don't!
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          function( arg1, arg2 )
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          ~~~
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * after a trailing comma
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          ~~~python
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Do
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          (0,)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Don't!
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          (0, )
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          ~~~
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * before commas, semicolons or colons
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          ~~~python
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Do
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          x, y = y, x
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Don't!
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          x , y = y , x
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          ~~~
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * around the slice operator `:`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * before an argument list
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          ~~~python
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Do
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          function(arg1, arg2)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Don't!
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          function (arg1, arg2)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          ~~~
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * before the indexing operator
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          ~~~python
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Do
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          dictionary["key"] = "Hello World!"
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          # Don't!
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          dictionary ["key"] = "Hello World!"
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          ~~~
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        #### Other
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Never use the semicolon for multiple statements; while allowed, it is discouraged as it hurts readability. Similarly discouraged are one-line clauses.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ### Strings
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Only use double quotes like `"` for strings: single quotes are harder to spot, and they conflict with the common apostrophe.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        For docstrings you should follow [PEP 257](https://peps.python.org/pep-0257/). Additionally, docstrings should use Markdown to allow for a future tool to convert them to docs.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        HOWEVER arguments should be described using the ReST syntax, as it is more readable in the code.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Other than this, they should be kept plaintext to prevent markup language battles (Python prefers
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        RST, but most use Markdown).
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ### Naming
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Identifiers must only use ASCII characters. Abbreviations should be kept to a minimum and it should be
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        made sure that they are widely used and accepted already.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        (`id` for `identifier` or `repo` for `repository` is acceptable, but `avg` for `average` is not). Generally, names should be easy to pronounce.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Class names must use `UpperCamelCase` with the first letter of each word capitalised and no underscores.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Other names (function, variable) should use `snake_case` with all words lowercase and separated by underscores.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        For instance and class methods, only name the first argument `self` or `cls`, respectively.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        To avoid conflicts, append an underscore or use a synonym but do not corrupt the spelling (`class_` is better than `clss` or `klass` or `classs` or whatever).
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Constants are an exception. They should use `UPPER_CASE` with underscores.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Non-public names should be prefixed with an underscore. In case it's really important to not use
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        them, use a double underscore to invoke name mangling.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ### Comments
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Block comments should be complete sentences; line comments don't need to. Write comments in
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        English and always use a space after the comment sign, as stated above, unless it's an UNIX
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        interpreter descriptor (`#!`) where you should not. Inside block comments, separate paragraphs
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        with an empty comment, like in Markdown. For a solo sentence, full stops are optional.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Avoid stating the obvious or contradicting the code.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Inline comments must be separated with more than one space from the statement, and they may be
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        aligned.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        In comments, never alter the case of identifiers, as it may lead to confusion.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Leaving TODO comments as personal notes is allowed, but they should be removed before merging
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        or a release.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Programming guidelines
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ----------------------
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ### OOP Guidelines
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Do not use getters and setters for class attributes. If you do need to change some other things,
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        use properties.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Prefer overloading the operators; make using your objects as natural and Pythonic as possible.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ### Exceptions
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Make exceptions specific enough, so catching them can be explicit.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Do not use the bare `except` clause. Make `try` clauses as short as possible to avoid silencing
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        unrelated bugs.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ### Other
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Comparisons to singletons (`True`, `False`, `None` etc.) should be done with the identity operators
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        `is` and `is not`, not with the comparison operators. Use `is not`, not `not ... is`.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Unless it would be ambiguous, use the implicit truth test to check that numbers are different to
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        0, that containers have contents and similar tests.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Do not assign lambdas to identifiers. Make a real function instead.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Use `with` context managers to ensure resources are properly cleaned up.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Prefer making functions that take arguments and return a value instead of making them directly take
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        global variables or process the information such as writing.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Use the methods `startswith()` and `endswith()` instead of string slicing to check for prefixes
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        or suffixes.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        To compare types, use `isinstance()` instead of the `is` operator with `type()` (this is one of
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        my problems with Python, but it's the standard).
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Use a proper condition for `while` instead of a `while True` that `break`s.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Use `for` loops instead of `while` loops when possible, and use Pythonic iteration instead of
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        C-style iteration.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        To call shells, use the `subprocess` module instead of `os.system()` and use the functions
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        that allow giving a *list* of arguments instead of a string, it leads to better security.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Similarly, avoid writing SQL manually, use Alchemy. If you must write SQL manually, be extra
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        careful.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Jinja style guide
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        -----------------
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Jinja should be written like Python, with the following additions:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Tags should be written as `{% <content> %}` and expressions as `{{ <content> }}`. That is,
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        put spaces around the content.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Always indent tag contents, just like you would indent HTML tags! If a tag contains other tags
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        and it wouldn't disrupt whitespace, you should indent the contents. An exception can be made
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        for top-level `{% block %}` tags, because indenting them would add an extra level of indentation
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        to all HTML.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        The filter operator `|` should have spaces around it, unless it's in a more complex expression
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        when it shouldn't.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Translations should always be done with the `{% trans %}` tag provided by Babel, not with
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        `gettext()`, `_()` or others. No exceptions.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        The quoting rules are as in Python, unless it's in an HTML attribute, in which case you should
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        use single quotes, as HTML takes precedence.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        If you're trying to use some function that transforms or checks values, create additional filters
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        or tests; they look cleaner.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        HTML style guide
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ----------------
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        HTML tags should be written in lowercase, with attributes in lowercase as well. Attribute values
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        should be quoted with double quotes. Attribute minimisation is suggested for boolean attributes.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Always indent tag contents with 4 spaces, except in plaintext tags like `pre` or `textarea`, where
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        you should not indent as it affects rendering.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        The tag should be multiple lines if the content is complex. Otherwise, mirror the page layout
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        - so use:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ```html
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        <button>Label</button>  <!-- Good, because the content is simple AND the button is inline -->
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        <p>                     <!-- Good, because even though the content is simple, the tag is a block -->
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            Content
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        </p>
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        <button>                <!-- Good, because the content is complex -->
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            <iconify-icon icon="mdi:plus"></iconify-icon>
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            Add
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        </button>
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ```
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        IDs or classes should be written in `kebab-case`. Names should be written in `snake_case` to
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        provide better compatibility with Python.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Also, when making custom tags, always use a hyphen in the tag name, to make sure they won't be
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        standardised in the future.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Inline CSS and JS should end with a semicolon, even if it's the only instruction.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        CSS style guide
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ---------------
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        CSS selectors, properties and values should be written in lowercase. Custom properties should be
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        written in `kebab-case`.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Always indent the contents of a ruleset with 4 spaces.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Unlike some other style guides, we do not require each selector after a comma to be on a new line.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        However, if they're too long, very complex or similar and they benefit from alignment, you should
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        do so.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        IDs are preferred over classes when the element only appears once on the page.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        JavaScript style guide
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ----------------------
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        JS should use double quotes for strings, and lowerCamelCase for names, and indenting should be 4 spaces.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Otherwise I can't comment, because JS is ugly by nature. Try to make it as readable as possible
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        and consistent with the other code. Also, use semicolons.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        `var` is not deprecated and may be the best choice in some cases. Use `let` for temporary variables,
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        but not `const`, as it provides a false sense of security by forbidding reassignment. However, if
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        you `const` a mutable object, you can still change its contents.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Web programming guidelines
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        --------------------------
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        As a modern web developer, you **will** be disappointed. In the roundabout project, we write
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        HTML and generate it on the server (which is not JavaScript, but Python/Flask). You may have
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        to relearn web development if you want to contribute.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Also, we use semantic HTML, which means we use tags for their intended purpose. If you're using
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        `<div>`, `<span>`, `<input>` and `<img>` for everything, you're doing it wrong.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        We don't like bloat either, so we don't use `<button class="btn btn-primary color-blue btn-large">`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        when `<button>` is enough. If you insist on something like Tailwind, you're in the wrong place.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        It does not mean we do web development like in 2004. We use the modern features browsers gift us:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * The powerful CSS layout engines, flexbox and gridbox
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * HTML5 semantic tags
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * JavaScript (plain!) for interactivity
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * SVG
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * Web fonts
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        and, most importantly, we use Flask, which didn't even exist in 2004.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        In short:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * The roundabout is not a SPA.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * JS should be used to enhance the experience, not to create it.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * We don't use client-side frameworks.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * The server is a safe environment, so we can access the database and filesystem right from the
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                          server-side code.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * JSON APIs are for specialised clients, not for the web interface.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * This is a Python project, not a JavaScript project; treat it as such.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * For live updates, get a segment of HTML, not JSON.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ### HTML
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Use semantic tags where possible, and minimise the reliance of classes. If more than 10% of your
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        tags are `<div>` or `<span>`, you're doing it wrong.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Use `id` if there is only one instance of the element on the page, not `class`.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Don't define custom attributes except `data-*` attributes.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ### CSS
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Tag selectors are **allowed**! Style the default widgets as you see fit, because it leads to
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        cleaner HTML. We also apply a reset stylesheet to make sure the default styles are consistent.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        In what scenario would you want an *unstyled* button in your site? Never! Then why always use
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        `<button class="btn btn-primary">` when it's the only kind of `<button>` your site has?
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        However, provide class-based alternatives for tag styles. For example, Efficient UI styles
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        `button` by default, but it also styles `.button` to allow hyperlinks or other elements to look
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        like buttons. Using both isn't needed though.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Also, selectors can be nested where it makes sense, however the `>` selector is preferred over
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        plain nesting, which is generally discouraged.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        For more information, read my article,
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        [Let's write more semantic CSS](https://roundabout.roundabout-host.com/articles/semantic-css.html).
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Use of fancy counters and data-attributes is allowed, but only for cosmetic purposes. We've got
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        server-side templating, profit from it!
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Inline CSS is only allowed to affect layout, *not* appearance.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        New, application-specific styles should be added to `/static/style.css`. The CSS framework
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        located in `/static/efficient-ui/*` should be kept reusable and generic; it will be published
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        separately in the future. Improvements to the framework are welcome, but they should keep these
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        goals in mind.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        ### JavaScript
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Event attributes are allowed, but please keep the JS inside shorter than a few tens of characters
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        and limited to a single instruction. If you need more, use a separate script tag. Acceptable event
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        JS includes, but is not limited to:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * `document.getElementById("dialog").showModal();`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * `document.getElementById("id").classList.toggle("class");`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * `myFunction();`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        * `document.getElementById("id").innerText = this.value;`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        If you're repeating the same event handler, put a class on the element and use `addEventListener`;
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        it will produce smaller HTML.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Scripts should be small, independent and reusable, only added to the pages that require them,
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        in the Jinja block `{% block scripts %}`.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Other
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        -----
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        You may not call third-party JavaScripts or CSS; you must copy them to the repository. If you
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        do, make sure they are licensed under a compatible licence.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Do not add features to snoop on users.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        Make sure the site stays clean and loads quickly.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                            
                                

doc/internal/Style guide.md