As machine learning projects grow in complexity, simply writing code that works is not enough. The ability to easily understand, modify, and reuse code components becomes essential for efficiency and collaboration. Thoughtful design of functions and modules directly addresses these requirements. These elements are the building blocks of a clean, maintainable, and scalable codebase.
Functions allow you to encapsulate a specific piece of logic, give it a name, and execute it whenever needed. Well-designed functions significantly improve code readability and reduce repetition. Here are key principles to follow when writing functions for your ML workflows:
Each function should have a single, well-defined purpose. A function named load_and_preprocess_data is likely doing too much. It violates the Single Responsibility Principle (SRP). If you need to change how missing data is handled, you have to modify a large function that also deals with file loading and maybe feature scaling.
Instead, break it down:
def load_data(file_path: str) -> pd.DataFrame:
"""Loads data from a CSV file."""
# Implementation for loading data
pass
def handle_missing_values(df: pd.DataFrame, strategy: str = 'mean') -> pd.DataFrame:
"""Imputes or removes missing values."""
# Implementation for handling NaNs
pass
def scale_features(df: pd.DataFrame, columns: list) -> pd.DataFrame:
"""Scales specified numerical features."""
# Implementation for feature scaling
pass
This approach makes the code easier to understand, test, and modify. If the data loading format changes, you only need to update load_data.
Function names should clearly indicate their purpose. Use verbs for actions (e.g., calculate_accuracy, train_model, plot_confusion_matrix) and follow consistent naming conventions, typically snake_case as recommended by PEP 8. Avoid vague names like process_data or run_analysis. Be specific about what is being processed or analyzed.
Long functions are harder to read, understand, and debug. If a function spans multiple screens, it's often a sign that it's doing too much and should be broken down into smaller, helper functions. There's no strict rule on length, but aim for functions that focus on a single logical step.
Functions communicate with the rest of your code through their parameters (inputs) and return values (outputs).
typing module) significantly improve clarity. They declare the expected types for parameters and the return value. This acts as documentation and allows static analysis tools to catch potential errors.from typing import List, Tuple
import numpy as np
def calculate_iou(box1: List[int], box2: List[int]) -> float:
"""Calculates the Intersection over Union (IoU) for two bounding boxes.
Args:
box1: A list representing the first bounding box [x_min, y_min, x_max, y_max].
box2: A list representing the second bounding box [x_min, y_min, x_max, y_max].
Returns:
The IoU score as a float between 0.0 and 1.0.
"""
# Implementation ...
iou = 0.0 # Placeholder
return iou
Every non-trivial function should have a docstring explaining what it does, its parameters, what it returns, and any exceptions it might raise. This is fundamental for maintainability, especially when working in teams or revisiting your own code later. Popular formats include Google style and NumPy style.
import pandas as pd
def summarize_dataframe(df: pd.DataFrame) -> dict:
"""Provides a basic summary of a Pandas DataFrame.
Args:
df: The input Pandas DataFrame.
Returns:
A dictionary containing summary statistics:
'num_rows': Number of rows.
'num_cols': Number of columns.
'missing_counts': Series with counts of missing values per column.
Raises:
TypeError: If the input is not a Pandas DataFrame.
"""
if not isinstance(df, pd.DataFrame):
raise TypeError("Input must be a Pandas DataFrame.")
summary = {
'num_rows': len(df),
'num_cols': len(df.columns),
'missing_counts': df.isnull().sum()
}
return summary
Consistent docstrings make your code understandable without needing to read the implementation details.
As your project grows, putting all your functions into a single file becomes unmanageable. Python's module system allows you to organize related code into separate files (.py files are modules) and directories (packages).
data_loader.py, all preprocessing steps in preprocessing.py).preprocessing.calculate_mean() is distinct from evaluation.calculate_mean().Simply save your Python code in a .py file. For instance, create a file named feature_engineering.py:
# feature_engineering.py
import pandas as pd
from typing import List
def create_polynomial_features(df: pd.DataFrame, columns: List[str], degree: int = 2) -> pd.DataFrame:
"""Creates polynomial features for specified columns."""
df_poly = df.copy()
for col in columns:
for d in range(2, degree + 1):
df_poly[f'{col}_pow{d}'] = df_poly[col] ** d
return df_poly
def create_interaction_features(df: pd.DataFrame, col1: str, col2: str) -> pd.DataFrame:
"""Creates an interaction feature between two columns."""
df_interact = df.copy()
df_interact[f'{col1}_x_{col2}'] = df_interact[col1] * df_interact[col2]
return df_interact
Now, in another script (e.g., main_script.py), you can import and use these functions:
# main_script.py
import pandas as pd
import feature_engineering as fe # Import the module
# Assume 'my_data' is a pandas DataFrame
# my_data = pd.read_csv(...)
# Apply functions from the module
numerical_cols = ['age', 'income']
my_data_poly = fe.create_polynomial_features(my_data, numerical_cols, degree=3)
my_data_final = fe.create_interaction_features(my_data_poly, 'age', 'income')
print(my_data_final.head())
Alternatively, you can import specific functions:
# main_script.py (alternative import)
import pandas as pd
from feature_engineering import create_polynomial_features
# ...
my_data_poly = create_polynomial_features(my_data, ['age', 'income'])
For larger projects, you can group related modules into directories. To make Python treat a directory as a package (from which you can import modules), include an empty file named __init__.py in that directory.
A typical ML project structure might look like this:
my_ml_project/
├── data/ # Raw and processed data
│ ├── raw/
│ └── processed/
├── notebooks/ # Jupyter notebooks for exploration
├── src/ # Source code
│ ├── __init__.py
│ ├── data_loader.py
│ ├── preprocessing.py
│ ├── feature_engineering.py
│ ├── models.py
│ ├── training.py
│ ├── evaluation.py
│ └── utils.py # Common utility functions
├── tests/ # Unit tests
│ ├── test_preprocessing.py
│ └── ...
├── requirements.txt # Project dependencies
└── main.py # Main script to run pipelines
A common directory structure for organizing a machine learning project, separating data, notebooks, source code (src), and tests.
From main.py or notebooks, you could import like this:
from src.preprocessing import handle_missing_values
from src.feature_engineering import create_polynomial_features
from src.models import train_linear_regression
The __init__.py file can also be used to control what symbols are exposed when using from package import * (though this import style is generally discouraged for clarity) or to run package initialization code.
A common issue is creating circular dependencies, where module A imports module B, and module B imports module A. This often happens when modules are not well-defined or try to do too much. Python will raise an ImportError in such cases. Proper structuring, adhering to the single responsibility principle for modules, and sometimes consolidating closely related functions or using utility modules can help prevent this.
By applying these principles for writing functions and organizing them into modules, you create a codebase that is significantly easier to manage, test, debug, and extend. This foundation is indispensable for building reliable and effective machine learning systems.
Was this section helpful?
© 2026 ApX Machine LearningAI Ethics & Transparency•