diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..be958c4 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,8 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +indent_style = tab +indent_size = 4 diff --git a/.gitignore b/.gitignore index d3ab421..af8167c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ .* !.git* +!.editorconfig __pycache__/ /venv/ diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst new file mode 100644 index 0000000..0a354f7 --- /dev/null +++ b/CODING_STYLE.rst @@ -0,0 +1,73 @@ +For consistency, here are some rules on how to format code. This is just my own +coding style, but it is worth putting it down, so that a consistent code can be +made. + +Indent by tabs. Tabs are expected to be 4 characters wide. (If your editor +supports editorconfig_, this should happen automatically) + +.. _editorconfig: https://editorconfig.org + +When performing a simple action in an ``if``, perform the action on the same +line:: + + if we_dont_care: continue + if it_is_broken: raise ValueError('Broken!') + if i_want(y): wanted.append(y) + +Using the elipsis (``...``) means there is some code missing. Do not use it in +other sense. + +Type hints are good. Write typehints to anything non-obvious. Especially, if +there is an empty dictionary being initialised, please say what you will store +in it. You may need to also write a comment about what the specific value is:: + + edges: dict[int, tuple[str, int]] = dict() # edge id → label, cost + +However, being slave to type checker is bad. The code should be readable +primarily by people, not by computers. Do not reorder the code or add weird +comments just to make mypy happy. Instead, just add something like ``# fuck +mypy vX.Y.Z`` to notify the programmer that it disagrees. In this case, always +add the version of broken type checker. (Comments like ``# mypy +ignore[import]`` are distracting and may be too cryptic for people.) + +There is no need to add hints to everything. Do not add superfluous hints, like +in ``count: int = 0``. Again, think of the people reading the code, not the +computer. + +Use simple type hints. Rather than ``Optional[int]``, use ``int | None``. If +python disagrees, put the hint into string and move on. (Hints like +``Optional[Union[IPv4Address, IPv6Address, Sequence[Union[IPv4Address, +IPv6Address]]]]`` are horrible to both read and edit. Use ``IPv4Address | +IPv6Address | Sequence[IPv4Address | IPv6Address] | None`` + +When creating empty dictionaries and sets, use the explicit constructor +(``set()``, ``dict()``) This is of course not needed when using +setcomps/dictcomps or for lists. + +Try to match style of surrounding / other code. + +Do not be afraid to write long comments. Use Unicode characters in comments and strings +(like en-dashes, elipses, quotes, &c.). However, python does not like if you use +``…`` in code. + +Use f-strings, not ``str.format`` or %-substitution. When you need to match +some exact text, use a r-string (even when it is a clear text, not regex, …). +In the unlikely case you need a multi-line string, use ``textwrap.dedent``. + +Aligning ifs when they fill the role of a switch is nice. You may add a dummy +line to ensure the alignment:: + + if False: pass # alignment + elif a.startswith('boo'): + cow() + elif a.startswith('meow'): + nya() + else: + stupid_human() + +Follow `PEP-20`_ rather than `PEP-8`_. + +.. _PEP-20: https://peps.python.org/pep-0020/ +.. _PEP-8: https://peps.python.org/pep-0008/ + +Have a lot of fun.