# Clean Code Principles

Sections like this are often skipped by readers, mostly because it is boring. But please do not skip this part as it is extremely important. I will try to make it as interesting as short as possible. 

```{image} ../static/WhenIWroteThisCode.png
:alt: When I wrote this code
:width: 400px
:align: center
```

Whenever you are working on code yourself, on small projects, we tend to write down everthing quick for that specific problem. Most of the time this will lead to buggy, hard coded, ugly, and inefficient code. When working on this code, you still know what everything means and it is not really a big problem. However, it will be when you are working together on bigger projects like DataBallPy. Others will not be able to read the code, optimize it, make changes, and build new features on top of it. However, this is exactly what we want; to improve the package. The most important thing to make this possible is to write clean code, simple as that. Or is it? Whole books have been written on the subject, writing code is like an art if done right. It is readable, efficient, scalable, clear, and short. Below are listed a few points to focus on with regard to writing clean code to get you started. Also try to read other people's code, this will make you appreciate clean code and realise the importance of it. Reading someones bad written code is one of the most frustating things I can think of. So lets get started with the list:

1. **Clear Variable Naming:** Clear and descriptive variable naming is crucial in writing maintainable and understandable code. Choosing meaningful names for variables enhances code readability, makes the code self-explanatory, and facilitates collaboration among developers. Consider the example of calculating acceleration from position data. Instead of using vague or generic variable names like `a`, `x`, or `t`, it is far more beneficial to use descriptive names that reflect the purpose of the variables involved. For instance: `acceleration`, `x_position`, `y_position`, `timestamp`. In general variable names should at least be 3 letters long and really tell something about what the variable is. It may also hold information about what type of variable it is: `home_players_list`. This clarity not only aids in understanding the code at first glance but also assists future maintenance and debugging, as the intentions and context behind the variables are evident. Of course, you also do not want your variable names to be too long, but generally speaking developers tend to overuse abbrevehations to shorten the variable names. By prioritizing clear variable naming, developers can greatly enhance the readability and maintainability of their code. 
2. **Use Build-In Functions:** Python offers a rich set of built-in functions and methods that provide efficient and reliable solutions to common programming tasks. Utilizing these functions instead of reinventing the wheel helps to improve code quality and readability. For example, instead of writing a custom sorting algorithm, using the built-in `sorted()` function can simplify the code and make the intention more explicit. You can also choose to use functions from other packages. For instance, functions from `pandas` and `numpy` are highly optimized and computational efficient, they are almost always better then writing similar functions yourself, so why would you bother?
3. **Make Small Functions:** Breaking down complex tasks into smaller functions with well-defined responsibilities enhances code modularity and readability. Each function should perform a single task or a cohesive set of related tasks. This approach not only improves code organization but also enables easier testing, debugging, and reusability. To optimize the efficiency of your code, try to avoid loops as much as possible. In line with this, prevent nesting functions too deep. This will make the code hard to read and understand. 

```{image} https://remote-tools-images.s3.amazonaws.com/programmer-memes/10.jpg
:alt: Unlimitted nesting
:width: 800px
:align: center
```

4. **Add Docstrings and Comments:** Including clear and concise docstrings for functions and classes, along with comments throughout the code, helps to document the purpose, behavior, and usage of various components. Docstrings provide a reference for other developers and promote self-documenting code, while comments explain the rationale behind specific implementation choices or highlight important details that may not be immediately apparent. Maintainers will often ask for clear documentation and comments since the written code is less clear to them than to the contributor. This will also avoid the situation that happened in the image above since, in theory, everything in the code is cristal clear.
5. **Unittesting Code**: Writing automated unit tests is essential for ensuring the correctness and reliability of code. Unit tests validate individual components and functions, allowing developers to catch and fix issues early. By establishing a comprehensive suite of tests, developers can have confidence in the behavior of their code, detect regressions, and facilitate future maintenance and refactoring efforts. This is so important, and often neglected, that the next chapter will go more in dept into testing your code. 

Lastly, some of the rules of writing clean code can be automated. For instance, indents, spaces, white lines, import order, and others. DataBallPy uses the packages `black` and `flake8` to automatically format the code. Make sure your code is formatted accordingly, otherwise the GitHub actions will fail and you will not be able to merge your changes into the DataBallPy repository.