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
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.
|