Machine Learning Foundations - ML Coding Style Standard

Status: Draft standard Applies to: all course notebooks, starter files, worked examples, and reference code

Purpose

Code in this course should be easy for a beginner to read, rerun, and debug. The standard favours clear steps over clever shortcuts.

Imports

Use one import block near the top of the notebook.

from pathlib import Path

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from sklearn.dummy import DummyClassifier, DummyRegressor
from sklearn.metrics import accuracy_score, mean_absolute_error
from sklearn.model_selection import train_test_split

Only import tools used in the notebook. Avoid wildcard imports.

Constants

Define constants once near the top.

RANDOM_SEED = 42
DATA_PATH = Path("data") / "example.csv"
TARGET_COLUMN = "completed_course"

Use RANDOM_SEED for every split or model that accepts a random seed.

Naming

Use names that reveal the role of each object.

Avoid names like df2, stuff, final_final, and model1 unless the lesson is specifically about naming mistakes.

Notebook cell size

Keep each code cell focused on one idea:

• load data;
• inspect data;
• select columns;
• split data;
• fit baseline;
• fit candidate model;
• evaluate;
• explain.

Avoid long cells that load, clean, split, fit, and evaluate all at once.

pandas style

Prefer explicit column lists.

feature_columns = ["lessons_started", "practice_minutes", "prior_python_score"]
X = data[feature_columns]
y = data[TARGET_COLUMN]

Do not silently drop columns without explaining why.

scikit-learn style

Use the same pattern throughout the course:

model.fit(X_train, y_train)
predictions = model.predict(X_test)

When preprocessing is needed, use a Pipeline or ColumnTransformer so the fit/transform sequence is reproducible and less likely to leak information.

Baseline first

Every supervised modelling notebook must fit a simple baseline before the candidate model.

Classification:

baseline_model = DummyClassifier(strategy="most_frequent")

Regression:

baseline_model = DummyRegressor(strategy="median")

Output style

Use small tables for results instead of scattered print statements.

results_table = pd.DataFrame(
    {
        "model": ["Baseline", "Candidate"],
        "metric": ["accuracy", "accuracy"],
        "value": [baseline_accuracy, candidate_accuracy],
    }
)
results_table

When using a chart, include a nearby table or numeric summary so the lesson does not depend on colour or visual inspection alone.

Comments

Use comments to explain why a step exists, not to repeat the code.

Good:

# Split before fitting so the test rows remain unseen by the model.
X_train, X_test, y_train, y_test = train_test_split(...)

Weak:

# Create X_train and X_test.
X_train, X_test, y_train, y_test = train_test_split(...)

Safety rules

Course code must not:

• use real private data;
• ask learners to paste secrets or personal data;
• download live remote data during practice;
• write outside the course folder;
• overwrite source data;
• hide target or future-information columns inside feature tables;
• use destructive file operations; or
• require paid services, accounts, or API keys.

Final notebook check

Before a notebook is accepted, it must restart and run from top to bottom with the pinned runtime and no manual state from earlier cells.