Coding guidelines

Apart from the requirements (already stated above) regarding static code checks for PEP8 compliance, type checking, and linting, there are some additional guidelines for coding changes on the ARAX code-base:

1. If you are adding or modifying a line of code for debugging that will need to be removed or updated before you commit, make sure you add a line comment # :DEBUG:. This is important so you can ensure that debugging code doesn't leak through into the commit.
2. Please use modern type hints (from python3.10 or newer), so no uppercase Dict or List, and make sure to use | None instead of Optional.
3. Please review your code with a code LLM (e.g., Claude code or Copilot) to check for bugs before committing. Best results from LLM review seem to be when the LLM can see the code diffs in the context of the full ARAX code-base.
4. Please visually inspect every line of your code diffs with git diff before committing; this is the perfect opportunity to catch debug code (which would be indicated with a # :DEBUG: line comment) before it gets accidentally committed.
5. If you update the code in a function, it is best practice to bring it up to modern standard in terms of type hinting and PEP8 formatting. But be cautious about entirely reformatting (such as with black or whatever) a whole module for which another active-contributing team member has the vast majority of commits; check with her/him before making a major reformat.
6. If your code update introduces a new dependency on a PyPI distribution package, it is critical that you update the ARAX RTX/requirements.txt file with the version-pinned dependency. You then need to test the updated requirements.txt file, using venv/bin/pip install -r RTX/requirements.txt, to make sure it works as modified. If your code update introduces a dependency on a mypy types package like types-requests or whatever, you need to put that in RTX/dev-requirements.txt as a pinned dependency and test it with pip.
7. All newly contributed python code from the OSU team should adhere to the PEP8 Style Guide for Python Code. Among other things, this means: No hard tabs; four space indentation; max 79 characters per line; proper use of CamelCase or snake_case or CAPS_SNAKE_CASE; proper use of whitespace around infix operators; etc.
8. Where possible, try to minimize use of "path surgery", i.e., sys.path.append. Some path surgery is inevitable given the bifurcation of the code-base into RTX/code/UI/OpenAPI/python-flask-server and RTX/code/ARAX subtrees, but please try to minimize it, bearing in mind that ARAX is run using python -m so it should be able to interpret dotted imports like from openapi_server.models.node import Node.
9. Lazy module import is to be avoided if at all possible, since ARAX runs in a multithreaded environment. This avoids nasty race conditions in the context of circular imports (see below), which is probably the main reason lazy import is used. It is strongly preferred to eagerly import modules when the application server is starting up in single-threaded mode. See ARAX issue 2788 for details.
10. Circular module imports, while sometimes necessary, should be avoided if possible (requires at least one lazy import, and see item 1 above).