Đặt tên có ý nghĩa

01 Tên hé lộ ý định (Intention-Revealing)

Tên tốt trả lời ba câu: vì sao nó tồn tại, nó làm gì, dùng nó ra sao. Một biến d kèm comment "elapsed time in days" là dấu hiệu thất bại — hãy để chính cái tên nói:

d = 0          # elapsed time in days
                # tên cần comment mới hiểu → tên thất bại

elapsed_time_in_days = 0
days_since_creation = 0
file_age_in_days = 0        # tên tự nói, không cần comment

RAG  Trong pipeline truy hồi, tên mù mịt khiến code "ngầm" — phải đoán mới hiểu. Hãy làm rõ kiểu Minesweeper của Martin: getThem() / theList / số ma thuật 4 đều vô nghĩa.

def get_them(the_list):          # lấy "them" là gì?
    out = []
    for x in the_list:
        if x[0] == 4:            # 4 là gì? x[0] là gì?
            out.append(x)
    return out

def get_relevant_chunks(chunks):     # "them" = đoạn liên quan
    return [c for c in chunks if c.is_relevant()]
# c.is_relevant() ẩn x[0] == 4 sau một đối tượng Chunk có nghĩa

02 Tránh thông tin sai lệch (Avoid Disinformation)

Phải tránh để lại những manh mối giả làm mờ nghĩa của code. Ba cái bẫy hay gặp:

account_list = {"a": acc1, "b": acc2}   # thật ra là dict, không phải list
                                         # → "List" là manh mối giả

accounts = {"a": acc1, "b": acc2}       # không gợi kiểu cụ thể
account_group = {"a": acc1, "b": acc2}  # hoặc nêu rõ "nhóm"

03 Phân biệt có ý nghĩa (Meaningful Distinctions)

Khi hai thứ trong cùng tầm vực phải khác tên, hãy để cái khác biệt mang nghĩa, đừng chỉ khác cho qua trình biên dịch.

Tránh number-series (a1, a2, … aN)

RAG  Đánh số biến là phản đề của tên hé lộ ý định — chúng chẳng nói gì về ý định tác giả. Đặt tên theo vai trò:

def copy_chunks(a1, a2):       # a1, a2 không nói lên vai trò
    for i in range(len(a1)):
        a2[i] = a1[i]

def copy_chunks(source, destination):   # vai trò rõ ràng
    for i in range(len(source)):
        destination[i] = source[i]

Tránh "từ nhiễu" (noise words)

Các từ như Info, Data, the, a, an là nhiễu — chúng không tạo khác biệt thật. Product vs ProductInfo vs ProductData chẳng khác gì nhau; moneyAmount không phân biệt nổi với money, customerInfo với customer.

04 Phát âm & tìm kiếm được

Dùng tên phát âm được (Pronounceable)

Lập trình là một hoạt động xã hội: ta phải nói về code với nhau. Tên phát âm được mới thảo luận trôi chảy. genymdhms ("generation year-month-day-hour-minute-second") khiến cuộc họp thành trò đánh vần.

class DtaRcrd102:
    genymdhms = None        # đọc làm sao đây?
    modymdhms = None
    pszqint = "102"

class Customer:
    generation_timestamp = None     # đọc được, nói được
    modification_timestamp = None
    record_id = "102"

Dùng tên tìm kiếm được (Searchable)

RAG  Tên một ký tự và số ma thuật (magic number) gần như không thể grep ra. Chữ e là ký tự phổ biến nhất tiếng Anh → tên tệ nhất để tìm. Đặt số thành hằng có tên:

s = 0
for j in range(34):             # 34? t? 4? 5? tìm sao ra?
    s += (t[j] * 4) / 5

NUMBER_OF_TASKS = 34
REAL_DAYS_PER_IDEAL_DAY = 4
WORK_DAYS_PER_WEEK = 5

total = 0
for task in range(NUMBER_OF_TASKS):
    real_days = task_estimate[task] * REAL_DAYS_PER_IDEAL_DAY
    total += real_days / WORK_DAYS_PER_WEEK

05 Tránh mã hóa & mental mapping

Tránh mã hóa trong tên (Avoid Encodings)

Nhét thông tin kiểu/phạm vi vào tên làm tăng gánh nặng giải mã. Ngôn ngữ hiện đại có kiểu mạnh và IDE thông minh nên những lối mã hóa cũ đã lỗi thời:

Tránh "mental mapping"

Đừng bắt người đọc tự dịch tên của bạn sang khái niệm họ đã biết — đó là dấu hiệu lập trình viên chưa làm chủ. i, j, k chấp nhận được cho biến đếm vòng lặp phạm vi nhỏ (theo truyền thống) — nhưng không bao giờ dùng l vì dễ nhầm với số 1. Ở mọi nơi khác, tên một ký tự là lựa chọn tồi, và đừng dùng c chỉ vì a, b đã bị lấy.

class IShapeFactory:        # tiền tố "I" thừa
    pass

phone_string = "0900..."    # nhúng kiểu vào tên → đổi kiểu là sai tên
m_count = 0                 # tiền tố m_ không cần thiết

class ShapeFactory:         # interface tên sạch
    pass

phone_number = "0900..."    # tên theo khái niệm, không theo kiểu
count = 0                   # đủ rõ trong lớp/hàm nhỏ

06 Tên lớp, phương thức & đừng chơi chữ

Đừng chơi chữ & một từ cho một khái niệm

07 Thêm ngữ cảnh có ý nghĩa (Meaningful Context)

Hầu hết tên không tự mang nghĩa; ngữ cảnh giúp chúng nói lên điều cần nói. Hãy đặt tên vào trong những lớp, hàm, namespace có tên tốt. Khi đứng một mình, state có thể là trạng thái máy hay tên bang — gom vào Address thì rõ ngay.

RAG  Các biến địa chỉ rời rạc nên gom thành một lớp; trình biên dịch cũng "biết" chúng thuộc một khái niệm lớn hơn:

first_name = "..."     # các biến rời, đứng một mình thiếu ngữ cảnh
last_name  = "..."
street      = "..."
house_number = "..."
city = "..."
state = "..."          # state = trạng thái? hay tên bang?
zipcode = "..."

class Address:          # ngữ cảnh: mọi biến rõ ràng thuộc về địa chỉ
    def __init__(self, street, house_number, city, state, zipcode):
        self.street = street
        self.house_number = house_number
        self.city = city
        self.state = state          # trong Address → chắc chắn là "bang"
        self.zipcode = zipcode

08 Ghi nhớ nhanh