|
| 1 | +# Spaghetti code sucks - a case for writing clean, readable code |
| 2 | +## My code runs just fine, why should I read this? |
| 3 | +Adhering to code style guidelines is about more than just writing code that runs. Recount how many lines of poorly documented, ill-formatted code you have read in your life: do you recall this as a joyful experience? Simple checks before commiting / pushing code to a repository allows you to focus on tasks at hand, and spend less time on understanding, maintaining and refactoring code. |
| 4 | + |
| 5 | +**We can all write code that runs, but following conventions allows you to make the transition from writing code purely for yourself to writing code for yourself and others.** |
| 6 | + |
| 7 | +This document is meant to **convince** you that this is an endeavour worth your time and not to let you feel like joining a cult or like you are in an encounter with Jehova's witnesses at your doorstep. |
| 8 | +In most programming languages, there is more than one way of doing things. |
| 9 | +Languages like Python are well aware of this and serve you the meaningful, yet a little esoteric ``Zen of Python`` when prompted. |
| 10 | +Open a terminal and type |
| 11 | + |
| 12 | +```sh |
| 13 | +python3 -c "import this" |
| 14 | +``` |
| 15 | + |
| 16 | +This will show you the following: |
| 17 | + |
| 18 | +``` |
| 19 | +The Zen of Python, by Tim Peters |
| 20 | +
|
| 21 | +Beautiful is better than ugly. |
| 22 | +Explicit is better than implicit. |
| 23 | +Simple is better than complex. |
| 24 | +Complex is better than complicated. |
| 25 | +Flat is better than nested. |
| 26 | +Sparse is better than dense. |
| 27 | +Readability counts. |
| 28 | +Special cases aren't special enough to break the rules. |
| 29 | +Although practicality beats purity. |
| 30 | +Errors should never pass silently. |
| 31 | +Unless explicitly silenced. |
| 32 | +In the face of ambiguity, refuse the temptation to guess. |
| 33 | +There should be one-- and preferably only one --obvious way to do it. |
| 34 | +Although that way may not be obvious at first unless you're Dutch. |
| 35 | +Now is better than never. |
| 36 | +Although never is often better than *right* now. |
| 37 | +If the implementation is hard to explain, it's a bad idea. |
| 38 | +If the implementation is easy to explain, it may be a good idea. |
| 39 | +Namespaces are one honking great idea -- let's do more of those! |
| 40 | +``` |
| 41 | + |
| 42 | +A few lines stand out in this context: |
| 43 | +1. ``Readability counts.`` |
| 44 | +2. ``Special cases aren't special enough to break the rules.`` |
| 45 | +3. ``In the face of ambiguity, refuse the temptation to guess.`` |
| 46 | +4. ``If the implementation is hard to explain, it's a bad idea.`` |
| 47 | +5. ``If the implementation is easy to explain, it may be a good idea.`` |
| 48 | + |
| 49 | +A few less vague recommendations may come in handy for everyone who isn't Dutch, but let's conclude with a short summary first. |
| 50 | + |
| 51 | +## TLDR: __Following a predefined set of rules (that everybody agrees on) comes with a responsibility that gives you benefits in return__ |
| 52 | + |
| 53 | +Responsibilities: |
| 54 | +- You take accountability for the code that you write and the commits you push |
| 55 | +- You follow the conventions of your project group to the best of your abilities |
| 56 | + |
| 57 | +Benefits: |
| 58 | +- The code in a joint project will be easy to read and thus easier to understand |
| 59 | +- Consequently, you will spend less time on refactoring, debugging and maintaining code |
| 60 | +- Your codebase will look presentable and professional to anyone looking at your code. In this context it doesn't matter if this is a potential business partner, a higher-up, a colleague, a collaborator or - if you are a student - a supervisor grading your work |
| 61 | + |
| 62 | +## Count me in, how do I proceed? |
| 63 | + |
| 64 | +First, ask yourself if you are writing code for yourself or production code. |
| 65 | +Ideally, the task at hand shouldn't determine the quality of the code you write, but personal projects as well as research can already be hectic enough. |
| 66 | +The guiding question should be: Will someone other than me read this code? |
| 67 | +If your answer is ''no'', the following steps may not be strictly necessary in your case, but they won't hurt you. |
| 68 | + |
| 69 | +## Three steps to success |
| 70 | +1. Code formatting: `black` |
| 71 | +`black` is a code formatting tool that is readily available as a plugins for most IDEs. |
| 72 | +It removes the need to manually format your code by e.g. running in the background or via a pre-commit hook. |
| 73 | + |
| 74 | +2. Code style validation: `ruff` |
| 75 | +`ruff` is a tool that checks your code regarding its syntax and provides instructions on how to improve it. It |
| 76 | +includes many popular tools (like e.g. `pydocstyle`) in one joint framework written in Rust. Contrary to e.g. `flake8`, |
| 77 | +`ruff` is able to fix a multitude of occurring problems on its own, removing the need for tedious manual correction in |
| 78 | +a lot of cases. |
| 79 | + |
| 80 | +3. Git best practices & conventional commits |
| 81 | + - Fork the Project |
| 82 | + - Create your feature branch (`git checkout -b feature/AmazingFeature`) |
| 83 | + - Commit your changes (`'git commit -m 'feat: Add some amazing feature'`) |
| 84 | + - Use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) either via a plugin for your IDE of choice or via a pre-commit hook |
| 85 | + - Push to the branch (`git push origin feature/AmazingFeature`) |
| 86 | + - Open a Pull Request |
| 87 | + |
| 88 | +>You feel like this missing something? Let's talk about it! |
| 89 | +
|
| 90 | +## Installation guide: |
| 91 | +1. Install `pre-commit` |
| 92 | +```sh |
| 93 | +pip install pre-commit |
| 94 | +``` |
| 95 | +(Optional: Add `pre-commit` to your `requirements.txt`) |
| 96 | + |
| 97 | +3. Configure and add `.pre-commit-config.yaml` to the root of your project |
| 98 | +An exemplary `.pre-commit-config.yaml` with suggested configurations can be found [here](./.pre-commit-config.yaml). |
| 99 | + |
| 100 | +4. Run |
| 101 | +```sh |
| 102 | +pre-commit install |
| 103 | +``` |
| 104 | +5. Done! |
| 105 | +That's it, you are good to go! |
0 commit comments