In my previous article, I highlighted the importance of effective project management in Python development. Now, let\u2019s shift our focus to the code itself and explore how to write clean, maintainable code\u200a\u2014\u200aan essential practice in professional and collaborative environments.\u00a0<\/p>\n
- \n
- \nReadability & Maintainability:<\/strong> Well-structured code is easier to read, understand, and modify. Other developers\u200a\u2014\u200aor even your future self\u200a\u2014\u200acan quickly grasp the logic without struggling to decipher messy code.<\/li>\n
- \nDebugging & Troubleshooting:<\/strong> Organized code with clear variable names and structured functions makes it easier to identify and fix bugs efficiently.<\/li>\n
- \nScalability & Reusability:<\/strong> Modular, well-organized code can be reused across different projects, allowing for seamless scaling without disrupting existing functionality.<\/li>\n<\/ul>\n
So, as you work on your next Python project, remember:\u00a0<\/p>\n
Half of good code is Clean Code<\/a>.<\/p>\n
\nIntroduction<\/h2>\n
Python is one of the most popular and versatile Programming<\/a> languages, appreciated for its simplicity, comprehensibility and large community. Whether web development, data analysis, artificial intelligence or automation of tasks\u200a\u2014\u200aPython offers powerful and flexible tools that are suitable for a wide range of areas.<\/p>\n
However, the efficiency and maintainability of a Python<\/a> project depends heavily on the practices used by the developers. Poor structuring of the code, a lack of conventions or even a lack of documentation can quickly turn a promising project into a maintenance and development-intensive puzzle. It is precisely this point that makes the difference between student code and professional code.<\/p>\n
This article is intended to present the most important best practices for writing high-quality Python code. By following these recommendations, developers can create scripts and applications that are not only functional, but also readable, performant and easily maintainable by third parties.<\/p>\n
Adopting these best practices right from the start of a project not only ensures better collaboration within teams, but also prepares your code to evolve with future needs. Whether you\u2019re a beginner or an experienced developer, this guide is designed to support you in all your Python developments.<\/p>\n
\nThe code structuration<\/h2>\n
Good code structuring in Python is essential. There are two main project layouts: flat layout<\/strong> and src layout<\/strong>.<\/p>\n
The flat layout<\/strong> places the source code directly in the project root without an additional folder. This approach simplifies the structure and is well-suited for small scripts, quick prototypes, and projects that do not require complex packaging. However, it may lead to unintended import issues when running tests or scripts.<\/p>\n
![\"\ud83d\udcc2\"](\"https:\/\/i0.wp.com\/s.w.org\/images\/core\/emoji\/15.0.3\/72x72\/1f4c2.png?ssl=1\")
my_project\/\n\u251c\u2500\u2500 my_project\/ # Directly in the root\n\u2502 \u251c\u2500\u2500 ![\"\ud83d\udc0d\"](\"https:\/\/i0.wp.com\/s.w.org\/images\/core\/emoji\/15.0.3\/72x72\/1f40d.png?ssl=1\")
__init__.py\n\u2502 \u251c\u2500\u2500 main.py # Main entry point (if needed)\n\u2502 \u251c\u2500\u2500 module1.py # Example module\n\u2502 \u2514\u2500\u2500 utils.py\n\u251c\u2500\u2500 tests\/ # Unit tests\n\u2502 \u251c\u2500\u2500 test_module1.py\n\u2502 \u251c\u2500\u2500 test_utils.py\n\u2502 \u2514\u2500\u2500 ...\n\u251c\u2500\u2500 ![\"\ud83d\udcc4\"](\"https:\/\/i0.wp.com\/s.w.org\/images\/core\/emoji\/15.0.3\/72x72\/1f4c4.png?ssl=1\")
.gitignore # Git ignored files\n\u251c\u2500\u2500 pyproject.toml # Project configuration (Poetry, setuptools)\n\u251c\u2500\u2500 uv.lock # UV file\n\u251c\u2500\u2500 README.md # Main project documentation\n\u251c\u2500\u2500 LICENSE # Project license\n\u251c\u2500\u2500 Makefile # Automates common tasks\n\u251c\u2500\u2500 DockerFile # Automates common tasks\n\u251c\u2500\u2500 .github\/ # GitHub Actions workflows (CI\/CD)\n\u2502 \u251c\u2500\u2500 actions\/ \n\u2502 \u2514\u2500\u2500 workflows\/<\/code><\/pre>\nOn the other hand, the src layout<\/strong> (src is the contraction of source) organizes the source code inside a dedicated
src\/<\/code> directory, preventing accidental imports from the working directory and ensuring a clear separation between source files and other project components like tests or configuration files. This layout is ideal for large projects, libraries, and production-ready applications as it enforces proper package installation and avoids import conflicts.<\/p>\n my-project\/\n\u251c\u2500\u2500 src\/ # Main source code\n\u2502 \u251c\u2500\u2500 my_project\/ # Main package\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # Makes the folder a package\n\u2502 \u2502 \u251c\u2500\u2500 main.py # Main entry point (if needed)\n\u2502 \u2502 \u251c\u2500\u2500 module1.py # Example module\n\u2502 \u2502 \u2514\u2500\u2500 ...\n\u2502 \u2502 \u251c\u2500\u2500 utils\/ # Utility functions\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 __init__.py \n\u2502 \u2502 \u2502 \u251c\u2500\u2500 data_utils.py # data functions\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 io_utils.py # Input\/output functions\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 ...\n\u251c\u2500\u2500 tests\/ # Unit tests\n\u2502 \u251c\u2500\u2500 test_module1.py \n\u2502 \u251c\u2500\u2500 test_module2.py \n\u2502 \u251c\u2500\u2500 conftest.py # Pytest configurations\n\u2502 \u2514\u2500\u2500 ...\n\u251c\u2500\u2500 docs\/ # Documentation\n\u2502 \u251c\u2500\u2500 index.md \n\u2502 \u251c\u2500\u2500 architecture.md \n\u2502 \u251c\u2500\u2500 installation.md \n\u2502 \u2514\u2500\u2500 ... \n\u251c\u2500\u2500 notebooks\/ # Jupyter Notebooks for exploration\n\u2502 \u251c\u2500\u2500 exploration.ipynb \n\u2502 \u2514\u2500\u2500 ... \n\u251c\u2500\u2500 scripts\/ # Standalone scripts (ETL, data processing)\n\u2502 \u251c\u2500\u2500 run_pipeline.py \n\u2502 \u251c\u2500\u2500 clean_data.py \n\u2502 \u2514\u2500\u2500 ... \n\u251c\u2500\u2500 data\/ # Raw or processed data (if applicable)\n\u2502 \u251c\u2500\u2500 raw\/ \n\u2502 \u251c\u2500\u2500 processed\/\n\u2502 \u2514\u2500\u2500 .... \n\u251c\u2500\u2500 .gitignore # Git ignored files\n\u251c\u2500\u2500 pyproject.toml # Project configuration (Poetry, setuptools)\n\u251c\u2500\u2500 uv.lock # UV file\n\u251c\u2500\u2500 README.md # Main project documentation\n\u251c\u2500\u2500 setup.py # Installation script (if applicable)\n\u251c\u2500\u2500 LICENSE # Project license\n\u251c\u2500\u2500 Makefile # Automates common tasks\n\u251c\u2500\u2500 DockerFile # To create Docker image\n\u251c\u2500\u2500 .github\/ # GitHub Actions workflows (CI\/CD)\n\u2502 \u251c\u2500\u2500 actions\/ \n\u2502 \u2514\u2500\u2500 workflows\/<\/code><\/pre>\nChoosing between these layouts depends on the project\u2019s complexity and long-term goals. For production-quality code, the
src\/<\/code> layout is often recommended, whereas the flat layout works well for simple or short-lived projects.<\/p>\nYou can imagine different templates that are better adapted to your use case. It is important that you maintain the modularity of your project. Do not hesitate to create subdirectories and to group together scripts with similar functionalities and separate those with different uses. A good code structure ensures readability, maintainability, scalability and reusability and helps to identify and correct errors efficiently.<\/p>\n
\n
Cookiecutter<\/a> is an open-source tool for generating preconfigured project structures from templates. It is particularly useful for ensuring the coherence and organization of projects, especially in Python, by applying good practices from the outset. The flat layout and src layout can be initiate using a UV tool<\/a>. <\/p>\n<\/blockquote>\n
\nThe SOLID principles<\/h2>\n
SOLID programming is an essential approach to software development based on five basic principles for improving code quality, maintainability and scalability. These principles provide a clear framework for developing robust, flexible systems. By following the Solid Principles<\/a>, you reduce the risk of complex dependencies, make testing easier and ensure that applications can evolve more easily in the face of change. Whether you are working on a single project or a large-scale application, mastering SOLID is an important step towards adopting object-oriented programming best practices.<\/p>\n
S\u200a\u2014\u200aSingle Responsibility Principle (SRP)<\/strong><\/h3>\n
The principle of single responsibility means that a class\/function can only manage one thing. This means that it only has one reason to change. This makes the code more maintainable and easier to read. A class\/function with multiple responsibilities is difficult to understand and often a source of errors.<\/p>\n
Example:<\/strong><\/p>\n
# Violates SRP\nclass MLPipeline:\n\u00a0 \u00a0 def __init__(self, df: pd.DataFrame, target_column: str):\n\u00a0 \u00a0 \u00a0 \u00a0 self.df = df\n\u00a0 \u00a0 \u00a0 \u00a0 self.target_column = target_column\n\u00a0 \u00a0 \u00a0 \u00a0 self.scaler = StandardScaler()\n\u00a0 \u00a0 \u00a0 \u00a0 self.model = RandomForestClassifier()\n\u00a0 \u00a0 \u00a0 \u00a0 def preprocess_data(self):\n\u00a0 \u00a0 \u00a0 \u00a0 self.df.fillna(self.df.mean(), inplace=True)\u00a0 # Handle missing values\n\u00a0 \u00a0 \u00a0 \u00a0 X = self.df.drop(columns=[self.target_column])\n\u00a0 \u00a0 \u00a0 \u00a0 y = self.df[self.target_column]\n\u00a0 \u00a0 \u00a0 \u00a0 X_scaled = self.scaler.fit_transform(X)\u00a0 # Feature scaling\n\u00a0 \u00a0 \u00a0 \u00a0 return X_scaled, y\n\u00a0 \u00a0 \u00a0 \u00a0 def train_model(self):\n\u00a0 \u00a0 \u00a0 \u00a0 X, y = self.preprocess_data()\u00a0 # Data preprocessing inside model training\n\u00a0 \u00a0 \u00a0 \u00a0 self.model.fit(X, y)\n\u00a0 \u00a0 \u00a0 \u00a0 print(\"Model training complete.\")<\/code><\/pre>\nHere, the Report class has two responsibilities: Generate content and save the file.<\/p>\n
# Follows SRP\nclass DataPreprocessor:\n\u00a0 \u00a0 def __init__(self):\n\u00a0 \u00a0 \u00a0 \u00a0 self.scaler = StandardScaler()\n\u00a0 \u00a0 \u00a0 \u00a0 def preprocess(self, df: pd.DataFrame, target_column: str):\n\u00a0 \u00a0 \u00a0 \u00a0 df = df.copy()\n\u00a0 \u00a0 \u00a0 \u00a0 df.fillna(df.mean(), inplace=True)\u00a0 # Handle missing values\n\u00a0 \u00a0 \u00a0 \u00a0 X = df.drop(columns=[target_column])\n\u00a0 \u00a0 \u00a0 \u00a0 y = df[target_column]\n\u00a0 \u00a0 \u00a0 \u00a0 X_scaled = self.scaler.fit_transform(X)\u00a0 # Feature scaling\n\u00a0 \u00a0 \u00a0 \u00a0 return X_scaled, y\n\n\nclass ModelTrainer:\n\u00a0 \u00a0 def __init__(self, model):\n\u00a0 \u00a0 \u00a0 \u00a0 self.model = model\n\u00a0 \u00a0 \u00a0 \u00a0 def train(self, X, y):\n\u00a0 \u00a0 \u00a0 \u00a0 self.model.fit(X, y)\n\u00a0 \u00a0 \u00a0 \u00a0 print(\"Model training complete.\")<\/code><\/pre>\nO\u200a\u2014\u200aOpen\/Closed Principle (OCP)<\/strong><\/h3>\n
The open\/close principle means that a class\/function must be open to extension, but closed to modification. This makes it possible to add functionality without the risk of breaking existing code.<\/p>\n
It is not easy to develop with this principle in mind, but a good indicator for the main developer is to see more and more additions (+) and fewer and fewer removals (-) in the merge requests during project development.<\/p>\n
L\u200a\u2014\u200aLiskov Substitution Principle (LSP)<\/strong><\/h3>\n
The Liskov substitution principle states that a subordinate class can replace its parent class without changing the behavior of the program, ensuring that the subordinate class meets the expectations defined by the base class. It limits the risk of unexpected errors.<\/p>\n
Example :<\/strong><\/p>\n
# Violates LSP\nclass Rectangle:\n def __init__(self, width, height):\n self.width = width\n self.height = height\n\n def area(self):\n return self.width * self.height\n\n\nclass Square(Rectangle):\n def __init__(self, side):\n super().__init__(side, side)\n# Changing the width of a square violates the idea of a square.<\/code><\/pre>\nTo respect the LSP, it is better to avoid this hierarchy and use independent classes:<\/p>\n
class Shape:\n def area(self):\n raise NotImplementedError\n\n\nclass Rectangle(Shape):\n def __init__(self, width, height):\n self.width = width\n self.height = height\n\n def area(self):\n return self.width * self.height\n\n\nclass Square(Shape):\n def __init__(self, side):\n self.side = side\n\n def area(self):\n return self.side * self.side<\/code><\/pre>\nI\u200a\u2014\u200aInterface Segregation Principle (ISP)<\/strong><\/h3>\n
The principle of interface separation states that several small classes should be built instead of one with methods that cannot be used in certain cases. This reduces unnecessary dependencies.<\/p>\n
Example:<\/strong><\/p>\n
# Violates ISP\nclass Animal:\n def fly(self):\n raise NotImplementedError\n\n def swim(self):\n raise NotImplementedError<\/code><\/pre>\nIt is better to split the class
Animal<\/code> into several classes:<\/p>\n# Follows ISP\nclass CanFly:\n\u00a0 \u00a0 def fly(self):\n\u00a0 \u00a0 \u00a0 \u00a0 raise NotImplementedError\n\n\nclass CanSwim:\n\u00a0 \u00a0 def swim(self):\n\u00a0 \u00a0 \u00a0 \u00a0 raise NotImplementedError\n\n\nclass Bird(CanFly):\n\u00a0 \u00a0 def fly(self):\n\u00a0 \u00a0 \u00a0 \u00a0 print(\"Flying\")\n\n\nclass Fish(CanSwim):\n\u00a0 \u00a0 def swim(self):\n\u00a0 \u00a0 \u00a0 \u00a0 print(\"Swimming\")<\/code><\/pre>\nD\u200a\u2014\u200aDependency Inversion Principle (DIP)<\/h3>\n
The Dependency Inversion Principle means that a class must depend on an abstract class and not on a concrete class. This reduces the connections between the classes and makes the code more modular.<\/p>\n
Example:<\/strong><\/p>\n
# Violates DIP\nclass Database:\n def connect(self):\n print(\"Connecting to database\")\n\n\nclass UserService:\n def __init__(self):\n self.db = Database()\n\n def get_users(self):\n self.db.connect()\n print(\"Getting users\")<\/code><\/pre>\nHere, the attribute db of UserService depends on the class Database. To respect the DIP, db has to depend on an abstract class.<\/p>\n
# Follows DIP\nclass DatabaseInterface:\n\u00a0 \u00a0 def connect(self):\n\u00a0 \u00a0 \u00a0 \u00a0 raise NotImplementedError\n\n\nclass MySQLDatabase(DatabaseInterface):\n\u00a0 \u00a0 def connect(self):\n\u00a0 \u00a0 \u00a0 \u00a0 print(\"Connecting to MySQL database\")\n\n\nclass UserService:\n\u00a0 \u00a0 def __init__(self, db: DatabaseInterface):\n\u00a0 \u00a0 \u00a0 \u00a0 self.db = db\n\n\u00a0 \u00a0 def get_users(self):\n\u00a0 \u00a0 \u00a0 \u00a0 self.db.connect()\n\u00a0 \u00a0 \u00a0 \u00a0 print(\"Getting users\")\n\n\n# We can easily change the used database.\ndb = MySQLDatabase()\nservice = UserService(db)\nservice.get_users()<\/code><\/pre>\n
\nPEP standards<\/strong><\/h2>\n
PEPs (Python Enhancement Proposals) are technical and informative documents that describe new features, language improvements or guidelines for the Python community. Among them, PEP 8, which defines style conventions for Python code, plays a fundamental role in promoting readability and consistency in projects.<\/p>\n
Adopting the PEP standards, especially PEP 8, not only ensures that the code is understandable to other developers, but also that it conforms to the standards set by the community. This facilitates collaboration, re-reads and long-term maintenance.<\/p>\n
In this article, I present the most important aspects of the PEP standards, including:<\/p>\n
- \n
- Style Conventions (PEP 8): Indentations, variable names and import organization.<\/li>\n
- Best practices for documenting code (PEP 257).<\/li>\n
- Recommendations for writing typed, maintainable code (PEP 484 and PEP 563).<\/li>\n<\/ul>\n
Understanding and applying these standards is essential to take full advantage of the Python ecosystem and contribute to professional quality projects.<\/p>\n
\nPEP 8<\/strong><\/h3>\n
This documentation<\/a> is about coding conventions to standardize the code, and there exists a lot of documentation about the PEP 8. I will not show all recommendation in this posts, only those that I judge essential when I review a code<\/p>\n
Naming conventions<\/strong><\/h4>\n
Variable, function and module names should be in lower case, and use underscore to separate words. This typographical convention is called snake_case.<\/p>\n
my_variable\nmy_new_function()\nmy_module<\/code><\/pre>\nConstances are written in capital letters and set at the beginning of the script (after the imports):<\/p>\n
LIGHT_SPEED\nMY_CONSTANT<\/code><\/pre>\nFinally, class names and exceptions use the CamelCase format (a capital letter at the beginning of each word). Exceptions must contain an Error at the end.<\/p>\n
MyGreatClass\nMyGreatError<\/code><\/pre>\nRemember to give your variables names that make sense<\/strong>! Don\u2019t use variable names like v1, v2, func1, i, toto\u2026<\/p>\n
Single-character variable names are permitted for loops and indexes:<\/p>\n
my_list = [1, 3, 5, 7, 9, 11]\nfor i in range(len(my_liste)):\n\u00a0 \u00a0 print(my_list[i])<\/code><\/pre>\nA more \u201cpythonic\u201d way of writing, to be preferred to the previous example, gets rid of the i index:<\/p>\n
my_list = [1, 3, 5, 7, 9, 11]\nfor element in my_list:\n print(element )<\/code><\/pre>\nSpaces management<\/h3>\n
It is recommended surrounding operators (+, -, *, \/, \/\/, %, ==, !=, >, not, in, and, or, \u2026) with a space before AND after:<\/p>\n
# recommended code:\nmy_variable = 3 + 7\nmy_text = \"mouse\"\nmy_text == my_variable\n\n# not recommended code:\nmy_variable=3+7\nmy_text=\"mouse\"\nmy_text== ma_variable<\/code><\/pre>\nYou can\u2019t add several spaces around an operator. On the other hand, there are no spaces inside square brackets, braces or parentheses:<\/p>\n
# recommended code:\nmy_list[1]\nmy_dict{\"key\"}\nmy_function(argument)\n\n# not recommended code:\nmy_list[ 1 ]\nmy_dict{ \"key\" }\nmy_function( argument )<\/code><\/pre>\nA space is recommended after the characters \u201c:\u201d and \u201c,\u201d, but not before:<\/p>\n
# recommended code:\nmy_list= [1, 2, 3]\nmy_dict= {\"key1\": \"value1\", \"key2\": \"value2\"}\nmy_function(argument1, argument2)\n\n# not recommended code:\nmy_list= [1 , 2 , 3]\nmy_dict= {\"key1\":\"value1\", \"key2\":\"value2\"}\nmy_function(argument1 , argument2)<\/code><\/pre>\nHowever, when indexing lists, we don\u2019t put a space after the \u201c:\u201d:<\/p>\n
my_list= [1, 3, 5, 7, 9, 1]\n\n# recommended code:\nmy_list[1:3]\nmy_list[1:4:2]\nmy_list[::2]\n\n# not recommended code:\nmy_list[1 : 3]\nmy_list[1: 4:2 ]\nmy_list[ : :2]<\/code><\/pre>\nLine length<\/strong><\/p>\n
For the sake of readability, we recommend writing lines of code no longer than 80 characters long. However, in certain circumstances this rule can be broken, especially if you are working on a Dash project, it may be complicated to respect this recommendation\u00a0<\/p>\n
The
<\/code> character can be used to cut lines that are too long.<\/p>\nFor example:<\/p>\n
my_variable = 3\nif my_variable > 1 and my_variable < 10 \n and my_variable % 2 == 1 and my_variable % 3 == 0:\n print(f\"My variable is equal to {my_variable }\")<\/code><\/pre>\nWithin a parenthesis, you can return to the line without using the character. This can be useful for specifying the arguments of a function or method when defining or using it:<\/p>\n
def my_function(argument_1, argument_2,\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 argument_3, argument_4):\n\u00a0 \u00a0 return argument_1 + argument_2<\/code><\/pre>\nIt is also possible to create multi-line lists or dictionaries by skipping a line after a comma:<\/p>\n
my_list = [1, 2, 3,\n 4, 5, 6,\n 7, 8, 9]\nmy_dict = {\"key1\": 13,\n \"key2\": 42,\n \"key2\": -10}<\/code><\/pre>\nBlank lines<\/strong><\/h3>\n
In a script, blank lines are useful for visually separating different parts of the code. It is recommended to leave two blank lines before the definition of a function or class, and to leave a single blank line before the definition of a method (in a class). You can also leave a blank line in the body of a function to separate the logical sections of the function, but this should be used sparingly.<\/p>\n
Comments<\/strong><\/h3>\n
Comments always begin with the # symbol followed by a space. They give clear explanations of the purpose of the code and must be synchronized with the code, i.e. if the code is modified, the comments must be too (if applicable). They are on the same indentation level as the code they comment on. Comments are complete sentences, with a capital letter at the beginning (unless the first word is a variable, which is written without a capital letter) and a period at the end.I strongly recommend writing comments in English and it is important to be consistent between the language used for comments and the language used to name variables. Finally, Comments that follow the code on the same line should be avoided wherever possible, and should be separated from the code by at least two spaces.<\/p>\n
Tool to help you<\/strong><\/p>\n
Ruff<\/a> is a linter (code analysis tool) and formatter for Python code written in Rust. It combines the advantages of the flake8 <\/strong>linter and black <\/strong>and isort <\/strong>formatting while being faster.<\/p>\n
Ruff has an extension on the VS Code editor.<\/p>\n
To check your code you can type:<\/p>\n
ruff check my_modul.py<\/code><\/pre>\nBut, it is also possible to correct it with the following command:<\/p>\n
ruff format my_modul.py<\/code><\/pre>\nPEP 20<\/strong><\/h3>\n
PEP 20: The Zen of Python<\/a> is a set of 19 principles written in poetic form. They are more a way of coding than actual guidelines.<\/p>\n
\n
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren\u2019t special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one\u2013 and preferably only one \u2013obvious way to do it.
Although that way may not be obvious at first unless you\u2019re Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it\u2019s a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea \u2014 let\u2019s do more of those!<\/p>\n<\/blockquote>\nPEP 257<\/strong><\/h3>\n
The aim of PEP 257<\/a> is to standardize the use of docstrings.<\/p>\n
What is a docstring?<\/strong><\/p>\n
A docstring is a string that appears as the first instruction after the definition of a function, class or method. A docstring becomes the output of the
__doc__<\/code> special attribute of this object.<\/p>\ndef my_function():\n\u00a0 \u00a0 \"\"\"This is a doctring.\"\"\"\n\u00a0 \u00a0 pass<\/code><\/pre>\nAnd we have:<\/p>\n
>>> my_function.__doc__\n>>> 'This is a doctring.'<\/code><\/pre>\nWe always write a docstring between triple double quote
\"\"\"<\/code>.<\/p>\nDocstring on a line<\/strong><\/h3>\n
Used for simple functions or methods, it must fit on a single line, with no blank line at the beginning or end. The closing quotes are on the same line as opening quotes and there are no blank lines before or after the docstring.<\/p>\n
def add(a, b):\n \"\"\"Return the sum of a and b.\"\"\"\n return a + b<\/code><\/pre>\nSingle-line docstring MUST NOT reintegrate function\/method parameters. Do not do:<\/p>\n
def my_function(a, b):\n \"\"\" my_function(a, b) -> list\"\"\"<\/code><\/pre>\nDocstring on several lines<\/strong><\/h3>\n
The first line should be a summary of the object being documented. An empty line follows, followed by more detailed explanations or clarifications of the arguments.<\/p>\n
def divide(a, b):\n\u00a0 \u00a0 \"\"\"Divide a byb.\n\n\u00a0 \u00a0 Returns the result of the division. Raises a ValueError if b equals 0.\n\u00a0 \u00a0 \"\"\"\n\u00a0 \u00a0 if b == 0:\n\u00a0 \u00a0 \u00a0 \u00a0 raise ValueError(\"Only Chuck Norris can divide by 0\") return a \/ b<\/code><\/pre>\nComplete Docstring<\/strong><\/h3>\n
A complete docstring is made up of several parts (in this case, based on the numpydoc standard).<\/p>\n
- \n
- Short description: Summarizes the main functionality.<\/li>\n
- Parameters: Describes the arguments with their type, name and role.<\/li>\n
- Returns: Specifies the type and role of the returned value.<\/li>\n
- Raises: Documents exceptions raised by the function.<\/li>\n
- Notes (optional): Provides additional explanations.<\/li>\n
- Examples (optional): Contains illustrated usage examples with expected results or exceptions.<\/li>\n<\/ol>\n
def calculate_mean(numbers: list[float]) -> float:\n\u00a0 \u00a0 \"\"\"\n\u00a0 \u00a0 Calculate the mean of a list of numbers.\n\n\u00a0 \u00a0 Parameters\n\u00a0 \u00a0 ----------\n\u00a0 \u00a0 numbers : list of float\n\u00a0 \u00a0 \u00a0 \u00a0 A list of numerical values for which the mean is to be calculated.\n\n\u00a0 \u00a0 Returns\n\u00a0 \u00a0 -------\n\u00a0 \u00a0 float\n\u00a0 \u00a0 \u00a0 \u00a0 The mean of the input numbers.\n\n\u00a0 \u00a0 Raises\n\u00a0 \u00a0 ------\n\u00a0 \u00a0 ValueError\n\u00a0 \u00a0 \u00a0 \u00a0 If the input list is empty.\n\n\u00a0 \u00a0 Notes\n\u00a0 \u00a0 -----\n\u00a0 \u00a0 The mean is calculated as the sum of all elements divided by the number of elements.\n\n\u00a0 \u00a0 Examples\n\u00a0 \u00a0 --------\n\u00a0 \u00a0 Calculate the mean of a list of numbers:\n\u00a0 \u00a0 >>> calculate_mean([1.0, 2.0, 3.0, 4.0])\n\u00a0 \u00a0 2.5<\/code><\/pre>\nTool to help you<\/strong><\/h4>\n
VsCode\u2019s autoDocstring <\/a>extension lets you automatically create a docstring template.<\/p>\n
PEP 484<\/strong><\/h3>\n
In some programming languages, typing is mandatory when declaring a variable. In Python, typing is optional, but strongly recommended. PEP 484<\/a> introduces a typing system for Python, annotating the types of variables, function arguments and return values. This PEP provides a basis for improving code readability, facilitating static analysis and reducing errors.<\/p>\n
What is typing?<\/strong><\/h3>\n
Typing consists in explicitly declaring the type (float, string, etc.) of a variable. The typing module provides standard tools for defining generic types, such as Sequence, List, Union, Any, etc.<\/p>\n
To type function attributes, we use \u201c:\u201d for function arguments and \u201c->\u201d for the type of what is returned.<\/p>\n
Here a list of none typing functions:<\/p>\n
def show_message(message):\n\u00a0 \u00a0 print(f\"Message : {message}\")\n\ndef addition(a, b):\n\u00a0 \u00a0 return a + b\n\ndef is_even(n):\n\u00a0 \u00a0 return n % 2 == 0\n\ndef list_square(numbers):\n\u00a0 \u00a0 \u00a0 return [x**2 for x in numbers]\n\ndef reverse_dictionary(d):\n\u00a0 \u00a0 return {v: k for k, v in d.items()}\n\ndef add_element(ensemble, element):\n\u00a0 \u00a0 ensemble.add(element)\n\u00a0 return ensemble<\/code><\/pre>\nNow here\u2019s how they should look:<\/p>\n
from typing import List, Tuple, Dict, Set, Any\n\ndef show _message(message: str) -> None:\n\u00a0 \u00a0 print(f\"Message : {message}\")\n\ndef addition(a: int, b: int) -> int:\n\u00a0 \u00a0 return a + b\n\ndef is_even(n: int) -> bool:\n\u00a0 \u00a0 return n % 2 == 0\n\ndef list_square (numbers: List[int]) -> List[int]:\n\u00a0 \u00a0 return [x**2 for x in numbers]\n\ndef reverse_dictionary (d: Dict[str, int]) -> Dict[int, str]:\n\u00a0 \u00a0 return {v: k for k, v in d.items()}\n\ndef add_element(ensemble: Set[int], element: int) -> Set[int]:\n\u00a0 \u00a0 ensemble.add(element)\n\u00a0 \u00a0 return ensemble<\/code><\/pre>\nTool to help you<\/strong><\/h4>\n
The MyPy extension<\/a> automatically checks whether the use of a variable corresponds to the declared type. For example, for the following function:<\/p>\n
def my_function(x: float) -> float:\n return x.mean()<\/code><\/pre>\nThe editor will point out that a float has no \u201cmean\u201d attribute.<\/p>\n
![\"\"](\"https:\/\/i0.wp.com\/towardsdatascience.com\/wp-content\/uploads\/2025\/02\/image-25.png?resize=817%2C204&ssl=1\")
Image from author<\/figcaption><\/figure>\n The benefit is twofold: you\u2019ll know whether the declared type is the right one and whether the use of this variable corresponds to its type.<\/p>\n
In the above example, x must be of a type that has a mean() method (e.g. np.array).<\/p>\n
\nConclusion<\/strong><\/h2>\n
In this article, we have looked at the most important principles for creating clean Python production code. A solid architecture, adherence to SOLID principles, and compliance with PEP recommendations (at least the four discussed here) are essential for ensuring code quality. The desire for beautiful code is not (just) coquetry. It standardizes development practices and makes teamwork and maintenance much easier. There\u2019s nothing more frustrating than spending hours (or even days) reverse-engineering a program, deciphering poorly written code before you\u2019re finally able to fix the bugs. By applying these best practices, you ensure that your code remains clear, scalable, and easy for any developer to work with in the future.<\/p>\n
\nReferences<\/strong><\/h2>\n
1. src layout vs flat layout<\/a><\/p>\n
2. SOLID principles<\/a><\/p>\n
3. Python Enhancement Proposals index<\/a><\/p>\n
The post Data Science: From School to Work, Part II<\/a> appeared first on Towards Data Science<\/a>.<\/p>\n<\/div>\n
- \nDebugging & Troubleshooting:<\/strong> Organized code with clear variable names and structured functions makes it easier to identify and fix bugs efficiently.<\/li>\n