From 9e201559f98eeab12e8080306680d0458fad58e2 Mon Sep 17 00:00:00 2001
From: Pavel 'LEdoian' Turinsky <ledoian@matfyz.cz>
Date: Sat, 15 Jul 2023 14:07:10 +0200
Subject: [PATCH] Add a coding style and an editorconfig

---
 .editorconfig    |  8 ++++++
 .gitignore       |  1 +
 CODING_STYLE.rst | 73 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+)
 create mode 100644 .editorconfig
 create mode 100644 CODING_STYLE.rst

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.