You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
74 lines
2.8 KiB
ReStructuredText
74 lines
2.8 KiB
ReStructuredText
1 year ago
|
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.
|