🏆 Tiêu chuẩn — Python Basics

Các tiêu chuẩn và nguyên tắc viết code Python chuyên nghiệp dành cho Data Analyst

Tổng quan tiêu chuẩn buổi 7

Buổi 7 đánh dấu bước chuyển quan trọng: từ viết SQL query sang viết Python code. Bạn đã làm quen với data types, control flow, functions và file handling — nhưng viết code "chạy được" và viết code chuyên nghiệp là hai chuyện khác nhau. Trong thực tế, code của Data Analyst không phải viết rồi bỏ — nó sẽ được đồng nghiệp đọc, sửa, mở rộng, và chạy tự động hàng tuần.

Python có hệ thống tiêu chuẩn rõ ràng thông qua PEP (Python Enhancement Proposals) — các đề xuất cải tiến chính thức của cộng đồng Python. Buổi này tập trung vào 3 tiêu chuẩn cốt lõi:

• PEP 8 — Style Guide: quy tắc viết code đẹp, nhất quán
• PEP 257 — Docstring Conventions: cách viết tài liệu cho function
• Clean Code Principles — Nguyên tắc viết code sạch, dễ bảo trì

Theo khảo sát Python Developers Survey (JetBrains, 2025), 87% Python developer tuân thủ PEP 8, và 73% đánh giá docstring là yếu tố quan trọng khi đọc code người khác. Nắm vững các tiêu chuẩn này ngay từ đầu giúp bạn viết code DA đúng chuẩn công nghiệp.

📋 Danh sách tiêu chuẩn liên quan

#	Tiêu chuẩn	Tổ chức / Tác giả	Áp dụng cho Buổi 7
1	PEP 8 — Style Guide for Python Code	Python Software Foundation (Guido van Rossum, Barry Warsaw, Alyssa Coghlan)	Naming conventions, indentation, line length, imports
2	PEP 257 — Docstring Conventions	Python Software Foundation (David Goodger, Guido van Rossum)	Viết docstring cho functions xử lý dữ liệu
3	Clean Code Principles	Robert C. Martin ("Uncle Bob")	Readable, maintainable code — meaningful names, small functions

---

1️⃣ PEP 8 — Python Style Guide

Giới thiệu

PEP 8 là tài liệu tiêu chuẩn chính thức về coding style cho Python, được khởi tạo bởi Guido van Rossum (cha đẻ Python) vào năm 2001. PEP 8 không phải "luật bắt buộc" — nhưng trong thực tế, nó là chuẩn de facto mà 87% developer tuân thủ. Hầu hết mọi công ty, open-source project, và tool (VS Code, PyCharm, Jupyter) đều tích hợp PEP 8 checker.

Triết lý cốt lõi của PEP 8:

"Code is read much more often than it is written." — Code được đọc nhiều hơn được viết.

Đối với Data Analyst, điều này đặc biệt đúng: bạn viết script phân tích hôm nay, tuần sau quay lại đọc để cập nhật — hoặc đồng nghiệp đọc để review. Code tuân thủ PEP 8 = dễ đọc = ít bug = ít thời gian debug.

Áp dụng trong buổi học

Naming Conventions — Quy tắc đặt tên

Loại	Quy tắc	Ví dụ đúng ✅	Ví dụ sai ❌
Biến (variable)	snake_case — chữ thường, dấu _	total_revenue, order_count	TotalRevenue, ordercount
Hàm (function)	snake_case — chữ thường, dấu _	calculate_revenue(), read_csv_file()	CalculateRevenue(), readCSVFile()
Hằng số (constant)	UPPER_SNAKE_CASE — chữ in hoa	MAX_ROWS = 1000, TAX_RATE = 0.1	max_rows, taxRate
Class	PascalCase — viết hoa đầu mỗi từ	SalesReport, DataProcessor	sales_report, data_processor

Indentation — Thụt lề

Python dùng 4 spaces cho mỗi cấp thụt lề (không dùng Tab):

# ✅ Đúng — 4 spaces
def calculate_total(orders):
    total = 0
    for order in orders:
        if order["status"] == "completed":
            total += order["amount"]
    return total

# ❌ Sai — 2 spaces hoặc trộn tab + space
def calculate_total(orders):
  total = 0
  for order in orders:
    if order["status"] == "completed":
        total += order["amount"]   # trộn 2 spaces và 4 spaces!
  return total

Line Length — Độ dài dòng

Tối đa 79 ký tự mỗi dòng (hoặc 99 cho team đồng ý). Dùng \ hoặc ngoặc () để xuống dòng:

# ✅ Đúng — xuống dòng khi quá dài
total_revenue = (
    sum(order["amount"] for order in orders
        if order["status"] == "completed")
)

# ❌ Sai — quá dài, phải cuộn ngang mới đọc được
total_revenue = sum(order["amount"] for order in orders if order["status"] == "completed" and order["region"] == "Bắc")

Imports — Thứ tự import

# ✅ Đúng — import theo thứ tự chuẩn PEP 8
# 1. Standard library
import csv
import json
import os

# 2. Third-party packages
import pandas as pd

# 3. Local modules
from utils import calculate_revenue

# ❌ Sai — import lộn xộn, gom 1 dòng
import csv, json, os, pandas

Ví dụ thực tế

So sánh 2 đoạn code cùng chức năng — đọc CSV và tính tổng doanh thu:

# ❌ Code KHÔNG tuân thủ PEP 8
import csv,json
def f(x):
 d=[]
 r=csv.DictReader(x)
 for i in r:
  if i['status']=='completed':
   d.append(float(i['amount']))
 return sum(d)

# ✅ Code tuân thủ PEP 8
import csv
import json


def calculate_total_revenue(file_handle):
    """Tính tổng doanh thu từ các đơn hàng completed."""
    completed_amounts = []
    reader = csv.DictReader(file_handle)

    for row in reader:
        if row["status"] == "completed":
            amount = float(row["amount"])
            completed_amounts.append(amount)

    return sum(completed_amounts)

💡 Công cụ hỗ trợ PEP 8

Không cần nhớ hết quy tắc! Dùng linter để tự động kiểm tra:

• VS Code: cài extension Pylint hoặc Ruff — gạch đỏ ngay khi vi phạm PEP 8
• Google Colab: chạy !pip install pycodestyle → !pycodestyle your_file.py
• Black formatter: tự động format code theo PEP 8 — chạy black your_file.py

Checklist PEP 8

• [ ] Tên biến và function dùng snake_case
• [ ] Thụt lề 4 spaces (không dùng Tab)
• [ ] Mỗi dòng ≤ 79 ký tự
• [ ] Có 2 dòng trắng trước mỗi def ở top-level
• [ ] Import theo thứ tự: standard → third-party → local
• [ ] Dấu cách quanh toán tử: x = 1, không phải x=1
• [ ] Không có trailing whitespace cuối dòng

---

2️⃣ PEP 257 — Docstring Conventions

Giới thiệu

PEP 257 quy định cách viết docstring — chuỗi tài liệu mô tả function, class, module. Docstring là "hợp đồng" giữa bạn và người đọc code (bao gồm cả "bạn trong tương lai"). Trong môi trường DA, docstring giải thích: function này nhận input gì, xử lý gì, trả về gì.

Docstring khác comment: comment giải thích tại sao (# Calculate tax because client requires it), docstring giải thích cái gì ("""Calculate tax for a given order amount.""").

Áp dụng trong buổi học

One-line Docstring

Dùng cho function đơn giản, dễ hiểu ngay:

def calculate_total(amounts):
    """Tính tổng doanh thu từ danh sách amounts."""
    return sum(amounts)

Quy tắc:

• Dùng triple quotes """
• Viết trên 1 dòng — kể cả """
• Kết thúc bằng dấu chấm
• Mô tả function làm gì, không mô tả cách làm

Multi-line Docstring

Dùng cho function phức tạp, cần giải thích parameters và return:

def revenue_by_category(orders, category_name):
    """Tính doanh thu cho một danh mục sản phẩm cụ thể.

    Lọc các đơn hàng theo category, chỉ tính đơn completed,
    và trả về tổng doanh thu.

    Args:
        orders (list[dict]): Danh sách đơn hàng, mỗi đơn là dict
            với keys: 'category', 'status', 'amount'.
        category_name (str): Tên danh mục cần tính (vd: 'Điện Tử').

    Returns:
        float: Tổng doanh thu của danh mục. Trả về 0.0 nếu
            không có đơn hàng nào matched.

    Example:
        >>> orders = [
        ...     {"category": "Điện Tử", "status": "completed", "amount": 500000},
        ...     {"category": "Thời Trang", "status": "completed", "amount": 300000},
        ... ]
        >>> revenue_by_category(orders, "Điện Tử")
        500000.0
    """
    total = 0.0
    for order in orders:
        if (order["category"] == category_name
                and order["status"] == "completed"):
            total += float(order["amount"])
    return total

⚠️ Lỗi thường gặp với docstring

• Quên viết docstring — function không có mô tả, 2 tuần sau quay lại không hiểu
• Docstring lỗi thời — sửa function nhưng quên cập nhật docstring
• Mô tả cách làm thay vì mô tả chức năng: """Loop through list and add numbers""" → nên viết """Calculate total revenue."""

Checklist PEP 257

• [ ] Mỗi function có ít nhất one-line docstring
• [ ] Dùng triple double quotes """
• [ ] Dòng đầu tiên mô tả chức năng, kết thúc bằng dấu chấm
• [ ] Function phức tạp có Args, Returns, Example
• [ ] Docstring khớp với hành vi thực tế của function
• [ ] Module-level docstring ở đầu file .py

---

3️⃣ Clean Code Principles

Giới thiệu

Clean Code là tập hợp nguyên tắc viết code sạch, do Robert C. Martin ("Uncle Bob") hệ thống hóa trong cuốn sách cùng tên (2008). Dù không phải "tiêu chuẩn chính thức" như PEP, Clean Code là triết lý được công nhận rộng rãi trong software engineering — và áp dụng hoàn toàn cho Data Analyst viết Python.

Nguyên tắc cốt lõi: Code should read like well-written prose — code nên đọc như văn xuôi viết tốt.

Áp dụng trong buổi học

Meaningful Names — Tên biến có ý nghĩa

# ❌ Bad — tên biến không rõ ràng
def f(d):
    r = 0
    for i in d:
        if i["s"] == "c":
            r += i["a"]
    return r

# ✅ Good — đọc code = hiểu ý đồ
def calculate_completed_revenue(orders):
    total_revenue = 0
    for order in orders:
        if order["status"] == "completed":
            total_revenue += order["amount"]
    return total_revenue

Small Functions — Function nhỏ, làm 1 việc

# ❌ Bad — function quá dài, làm nhiều việc
def process_data(filename):
    # Đọc file (20 dòng)
    # Lọc dữ liệu (15 dòng)
    # Tính toán (25 dòng)
    # Ghi file (10 dòng)
    pass

# ✅ Good — chia nhỏ, mỗi function 1 nhiệm vụ
def read_sales_data(filename):
    """Đọc file CSV bán hàng."""
    ...

def filter_completed_orders(orders):
    """Lọc chỉ giữ đơn hàng completed."""
    ...

def calculate_revenue_stats(orders):
    """Tính các chỉ số doanh thu."""
    ...

def export_report(stats, output_path):
    """Ghi báo cáo ra file JSON."""
    ...

No Magic Numbers — Không dùng số "thần kỳ"

# ❌ Bad — 0.1 là gì? 1000000 là gì?
if revenue > 1000000:
    tax = revenue * 0.1

# ✅ Good — hằng số có tên rõ ràng
TAX_RATE = 0.1
HIGH_REVENUE_THRESHOLD = 1_000_000

if revenue > HIGH_REVENUE_THRESHOLD:
    tax = revenue * TAX_RATE

DRY — Don't Repeat Yourself

# ❌ Bad — lặp lại logic tính doanh thu
north_revenue = sum(o["amount"] for o in orders if o["region"] == "Bắc" and o["status"] == "completed")
south_revenue = sum(o["amount"] for o in orders if o["region"] == "Nam" and o["status"] == "completed")
central_revenue = sum(o["amount"] for o in orders if o["region"] == "Trung" and o["status"] == "completed")

# ✅ Good — tạo function tái sử dụng
def revenue_by_region(orders, region):
    """Tính doanh thu completed cho một vùng."""
    return sum(
        o["amount"] for o in orders
        if o["region"] == region and o["status"] == "completed"
    )

north_revenue = revenue_by_region(orders, "Bắc")
south_revenue = revenue_by_region(orders, "Nam")
central_revenue = revenue_by_region(orders, "Trung")

💡 Clean Code cho DA

Bạn không cần áp dụng 100% Clean Code ngay từ đầu. Bắt đầu với 3 quy tắc:

1. Đặt tên biến rõ ràng — revenue thay vì r
2. Mỗi function chỉ làm 1 việc — dưới 20 dòng
3. Không lặp code — thấy copy-paste → viết function

Checklist Clean Code

• [ ] Tên biến/function mô tả rõ mục đích
• [ ] Mỗi function chỉ làm 1 nhiệm vụ (≤ 20 dòng)
• [ ] Không có magic numbers — dùng constants
• [ ] Không lặp code — DRY principle
• [ ] Code đọc từ trên xuống dưới như câu chuyện

---

📊 Bảng tổng hợp

Tiêu chuẩn	Phạm vi	Áp dụng Buổi 7	Mức độ bắt buộc
PEP 8	Style — cách viết code	Naming, indentation, imports, line length	⭐⭐⭐ Gần như bắt buộc — 87% developer tuân thủ
PEP 257	Documentation — docstring	Viết docstring cho functions xử lý dữ liệu	⭐⭐ Nên tuân thủ — đặc biệt khi code chia sẻ
Clean Code	Design — thiết kế code	Meaningful names, small functions, DRY	⭐⭐ Nên tuân thủ — giúp code dễ bảo trì

⚠️ Quan trọng

Các tiêu chuẩn này không phải luật pháp — chúng là best practices được cộng đồng Python chấp nhận rộng rãi. Khi mới học, không cần hoàn hảo 100% — nhưng hãy hình thành thói quen từ đầu. Sửa habit xấu sau 6 tháng khó hơn nhiều so với làm đúng từ ngày đầu.

---

📚 Tài liệu tham khảo

Tài liệu	Link	Ghi chú
PEP 8 — Style Guide	peps.python.org/pep-0008	Tài liệu gốc chính thức
PEP 257 — Docstring Conventions	peps.python.org/pep-0257	Tài liệu gốc chính thức
Google Python Style Guide	google.github.io/styleguide/pyguide.html	Phiên bản Google — bổ sung PEP 8
Clean Code (Robert C. Martin)	ISBN: 978-0132350884	Sách gốc về Clean Code principles
Real Python — PEP 8 Tutorial	realpython.com/python-pep8	Hướng dẫn thực hành PEP 8 với ví dụ
Black Formatter	github.com/psf/black	Auto-formatter chuẩn PEP 8
Ruff Linter	github.com/astral-sh/ruff	Linter cực nhanh — kiểm tra PEP 8 + nhiều quy tắc