Why it matters in real projects ⏱️
Supportability — this is the speed of change without failures and nerves. The easier it is to read and test the code, the faster the releases and the fewer the bugs. These 5 mistakes are the most common — let's start with them.
❌ Magic numbers and strings
The non-obvious "3", "0.15" and "S" make you guess what it means.
# was
if user_status == 3:
discount = 0.15
# became
VIP_USER = 3
LOYALTY_DISCOUNT = 0.15
if user_status == VIP_USER:
discount = LOYALTY_DISCOUNT💡 Use constants, enumerations (Enum), and configs — the meaning becomes clear.
❌ Kilometer functions
The 150-line function does everything at once: it parses the input, validates it, writes to the database, and draws a report.
# break it down into steps
def parse_request(req): ...
def validate(data): ...
def save(data, db): ...
def build_report(data): ...
def handle(req):
data = parse_request(req)
validate(data)
save(data, db="main")
return build_report(data)Small functions are easier to test, reuse, and read.
❌ Code duplication
Copy-paste leads to a discrepancy in logic: in one place they corrected, in another they forgot.
# was (two similar tax calculation blocks)
def calc_tax_order(total): return total * 0.07
def calc_tax_invoice(total): return total * 0.07
# became
def calc_tax(amount, rate=0.07):
return amount * rate🔁 Move the repeated code to a function, class, or module; in templates, use macros/partials.
❌ Bad names
The names f, x, processData without context are mind-boggling.
# was
def f(x): return x*7/100
# became
def calculate_tax(price: float, tax_rate: float = 0.07) -> float:
return price * tax_rateLet's name by subject area: what exactly the entity considers/does.
❌ No comments and documentation
The code explains the "how", but often the answer to the "why" is needed. Complex decisions and assumptions without comments are a trap.
def allocate_slots(users):
"""
Distributes slots to users.
The algorithm is greedy: first VIP, then PRO, then FREE.
This is critical for SLA partners.
"""
...📚 Maintain README, docstrings, and short comments on non-trivial places.
📊 Summary: errors and how to fix them
Error | Why it is dangerous | Correction |
|---|---|---|
Magic numbers/lines | Loss of meaning, risks of incorrect edits | Constants, Enum, configs |
Long functions | Poorly tested, difficult to read | Decomposition into short steps |
Duplication | Logic discrepancy, bugs when changing | Removal to functions/modules |
Bad names | Reduced reading/onboarding speed | Names by domain logic |
No documentation | Failure to meet deadlines, dependence on "knowledge carriers" | Docstrings, README, short comments |
Mini checklist before PR ✅
Is there "magic" - numbers/lines without meaning?
Functions are shorter than ~30–40 lines and do one thing?
Removed the copy-paste? Repeated - in the general module.
Are names readable on the fly? (methods, variables, files)
Is there a docstrings/README for a beginner to enter?
Do the tests cover the key logic?
Where to train with good practices 💡
In Codice we make programming training fun and easy to understand: we have interesting courses with tasks that help you improve your skills step by step.
And we also have an active Telegram channel, where we discuss cool ideas, share experiences and analyze tasks together — learning becomes not only useful, but also fun.
Which of the five mistakes is most common in your projects?