Chú thích trong Python: một dòng, nhiều dòng và docstring

Chú thích là để cho người đọc

Python bỏ qua chú thích (comment). Bí quyết chỉ có vậy. Mọi thứ bạn đánh dấu là chú thích đều vô hình với trình thông dịch: nó chỉ ở đó cho người đọc code, mà thường chính là bạn sáu tháng sau, đang thắc mắc không biết bạn của ngày trước đã nghĩ gì.

Dù vậy, một chú thích chỉ lặp lại điều code đã thể hiện rõ thì không đáng viết. Chú thích tốt nhất giải thích vì sao: một ràng buộc, một cách xoay xở, một quyết định mà nhìn code không thấy ngay. Code đã cho bạn biết điều gì đang xảy ra.

Chú thích một dòng với #

Dạng cơ bản là dấu # theo sau là ghi chú của bạn:

# Calculate the tax portion of the total.
total = 100
tax = total * 0.08
print(tax)

Bạn cũng có thể thêm một chú thích ngắn vào cuối dòng. Theo quy ước, hãy để ít nhất hai dấu cách trước #:

refresh_interval = 300  # seconds; keep in sync with the dashboard config
print(refresh_interval)

Python coi dấu # ở bất kỳ đâu bên ngoài chuỗi là bắt đầu chú thích cho phần còn lại của dòng. Phần "bên ngoài chuỗi" rất quan trọng: # trong dấu nháy chỉ là một ký tự.

url = "https://example.com/#section-2"  # the real comment starts here
print(url)

#section-2 bên trong chuỗi là một phần của URL. Python chỉ chuyển sang chế độ "chú thích" với dấu # sau khi chuỗi đã đóng.

Comment nhiều dòng

Python không có chú thích khối kiểu /* */. Để bỏ qua nhiều dòng, hãy đặt # ở đầu mỗi dòng:

# This is a block comment.
# It spans several lines.
# Each line starts with its own #.
print("only this line actually runs")

Bạn gần như không bao giờ gõ tay những dấu # đó. Trình soạn thảo tử tế nào cũng có phím tắt "bật/tắt chú thích dòng", thêm hoặc bỏ # trên mọi dòng đang chọn:

• VS Code: Cmd + / (macOS) hoặc Ctrl + / (Windows/Linux)
• PyCharm: Cmd + / hoặc Ctrl + /
• Vim: tùy plugin của bạn; vim-commentary gán gcc cho một dòng và gc cho vùng chọn.

Học phím tắt trong trình soạn thảo của bạn một lần, và việc "comment khối này lại để thử cái khác" chỉ còn là một lần nhấn phím.

Mẹo chuỗi ba dấu nháy (và vì sao nó không thực sự là chú thích)

Đôi khi bạn sẽ gặp code như thế này:

"""
This block looks like a comment
but it's actually a string literal
that nothing uses.
"""
print("hi")

Về mặt kỹ thuật, đó là một biểu thức chuỗi bị bỏ đi. Python phân tích nó, tính giá trị rồi vứt kết quả. Nó hoạt động như chú thích, nhưng không phải chú thích. Về phong cách, cách này chỉ nên dùng ở đúng một chỗ: làm docstring.

Docstring: chỗ duy nhất dành cho ba dấu nháy

Docstring là một chuỗi ba dấu nháy đặt làm câu lệnh đầu tiên trong một hàm, lớp hoặc module. Python nhận ra nó là tài liệu và cho phép truy cập lúc chạy qua hàm help() và thuộc tính __doc__:

def discount(price, percent):
    """Return the final price after applying a percentage discount.

    price is a number; percent is between 0 and 100.
    """
    return price * (1 - percent / 100)

print(discount(50, 20))
help(discount)

Hai điều khiến docstring hữu ích:

1. Các công cụ như IDE, help() và trình tạo tài liệu tự động đọc chúng. Một chú thích phía trên hàm thì không được như vậy.
2. Chúng mô tả hàm ngay tại chỗ gọi: khi ai đó di chuột lên discount(...) trong trình soạn thảo, docstring hiện lên thành tooltip.

Có một quy ước (PEP 257) về nội dung docstring: tóm tắt một dòng ở dòng đầu, một dòng trống, rồi mô tả dài hơn nếu cần. Ngày đầu đừng lo về định dạng chính xác: một dòng đơn giản vẫn tốt hơn nhiều so với không có docstring nào.

Chú thích tốt thực sự nói gì

Vài nguyên tắc giúp bạn đỡ đau đầu về sau:

• Ưu tiên giải thích vì sao hơn là cái gì. # Loop over the users chỉ là nhiễu; # Retry on 503 - Redis sometimes dies mid-deploy mới là vàng.
• Cập nhật chú thích khi sửa code. Chú thích sai còn tệ hơn không có chú thích. Chú thích lỗi thời sẽ đánh lừa người đọc sau này.
• Đừng comment code rồi bỏ đó. Nếu không cần nữa, hãy xóa. Hệ thống quản lý phiên bản vẫn nhớ. Một tệp lốm đốm những khối code bị comment sẽ nhanh chóng mất độ tin cậy.
• Bỏ qua điều hiển nhiên. x = x + 1 # increment x chẳng thêm được gì.

Tóm lại

Chú thích viết thì không tốn gì, bỏ qua cũng dễ. Hãy dùng chúng khi bạn để lại một ghi chú mà người đọc sẽ cảm ơn: một lý do tinh tế khiến thứ gì đó chạy được, một đường link tới issue, một cảnh báo về trường hợp đặc biệt. Dùng docstring khi định nghĩa hàm hoặc lớp. Còn lại, hãy để những cái tên rõ ràng và các hàm nhỏ tự nói lên tất cả.

Giờ bạn đã có mọi thứ cần thiết để đọc và viết một tệp Python. Chương tiếp theo là nơi ngôn ngữ thực sự bắt đầu làm việc: biến, kiểu dữ liệu và những giá trị Python có thể lưu giữ.