Đến nội dung chính
notes.vinhnq.com

Tìm kiếm

OOP & Thiết kếMid21 phút đọc

Clean code: vì sao, đặt tên, hàm và luồng điều khiển

Ôn 18 thẻ
Trong bài này

Cụm bài Clean code: 1. Đặt tên, hàm và luồng điều khiển · 2. Xử lý lỗi, boundary và refactor

Ai cũng nhận ra code đẹp khi thấy nó; khó là biến cảm nhận đó thành quy tắc cả team dùng được, và biết khi nào không nên theo. Bài này đi từ lý do kinh tế, qua gốc của code bẩn (độ phức tạp), tới đặt tên, hàm, class và luồng điều khiển. Bài 2 nói về xử lý lỗi, boundary, test và một buổi refactor trọn vẹn.

1. Vì sao cần clean code

Ý chính: vì chi phí thay đổi. Code nhanh và bẩn rẻ hơn vài tuần đầu, rồi mỗi tính năng tốn công hơn và dễ làm vỡ chỗ khác hơn; đó là gốc chung của nhiều bug và ra thị trường chậm.

Chi phí code sạch tăng gần tuyến tính, code bẩn gần hàm mũ; hai đường cắt nhau sau vài tuần, không phải vài năm. Brian Foote và Joseph Yoder: nếu bạn nghĩ kiến trúc tốt là đắt, hãy thử kiến trúc tồi.

Khoá học cụ thể hoá thành bốn chữ “-able”:

  • Readable: người mới đọc hiểu một hàm mà không phải hỏi tác giả.
  • Maintainable: sửa một quy tắc nghiệp vụ chỉ đụng một chỗ.
  • Testable: test được logic mà không cần database, Kafka hay đồng hồ thật.
  • Scalable (theo nghĩa codebase): thêm người, thêm tính năng mà tốc độ không giảm.

Mục tiêu cuối, như kiến trúc sạch của Robert C. Martin, là giảm công sức con người để xây và bảo trì hệ thống; clean code chỉ là phương tiện.

Khi clean code đụng hiệu năng hoặc deadline

2. Code bẩn từ đâu ra: độ phức tạp

Ý chính: theo John Ousterhout (A Philosophy of Software Design), độ phức tạp là bất cứ thứ gì làm code khó hiểu hoặc khó sửa. Nó sinh từ phụ thuộc và sự mơ hồ, và lộ ra qua ba triệu chứng.

Gốc thứ hai trên slide là chủ quan: thiếu cảm nhận cái đẹp (không hỏi “vì sao”, không đọc code).

graph TD
  S[Code smell] --> C[Độ phức tạp]
  S --> B[Thiếu cảm nhận cái đẹp]
  C --> D[Phụ thuộc]
  C --> O[Mơ hồ]
  D --> CA((Change amplification))
  D --> CL((Cognitive load))
  O --> I[Thiếu nhất quán]
  I --> UU((Unknown unknowns))
  B --> W((Không hỏi vì sao))
  B --> R((Không đọc))
Nghĩa Ví dụ
Phụ thuộc (nguyên nhân) một đoạn code không hiểu hay sửa được độc lập ngưỡng miễn phí vận chuyển 500_000 viết cứng ở controller, service tính giá và template email
Mơ hồ (nguyên nhân) thông tin quan trọng không hiển nhiên field status kiểu int, không ai nhớ 3 là gì
Change amplification thay đổi đơn giản phải sửa nhiều nơi đổi ngưỡng phải sửa ba file
Cognitive load (gánh nặng nhận thức) phải nhớ quá nhiều mới sửa an toàn thứ tự gọi hàm, cờ nào bật ở đâu, field nào null được
Unknown unknowns không biết mình cần biết gì (tệ nhất) hai tuần sau mới thấy chỗ thứ tư dùng hằng số cũ

3. Luyện clean code thế nào

Ý chính: luyện theo hai hướng của định nghĩa. Dễ hiểu: đặt tên, quy ước, format, code review, static analysis (Checkstyle, Sonar, Error Prone). Dễ thay đổi: nguyên tắc thiết kế, design pattern, unit test, refactor.

KISS có hai vế: chia bài toán đủ nhỏ để hiểu, và không over-engineering (thiết kế quá mức cần). Một interface với đúng một implementation “để sau này mở rộng” thường không bao giờ hoàn vốn. Robert C. Martin: nếu Open-Closed là mục tiêu thì Dependency Inversion là cơ chế chính. OCP qua Strategy ở bài design pattern qua refactor, DIP ở bài IoC và DI; bài này chỉ áp SRP và OCP ở mức class.

Cách luyện và trình tự viết code khoá học đề xuất
  • Đọc code tốt (Spring Framework, Kafka client, Guava; ví dụ class KafkaProducerMetrics đọc một lượt là hiểu) và sách để có cảm nhận cái đẹp.
  • Kỷ luật nhưng thực dụng.
  • Thực hành với độ phức tạp thật: hiểu domain, sửa triệu chứng ngay khi thấy, refactor thường xuyên, pair programming.

Trình tự viết code:

  1. Viết tên các bước chính trước, như mục lục.
  2. Viết code theo các bước.
  3. Đọc lại và refactor một phần trước khi chạy thử, lúc bối cảnh còn nóng.
  4. Unit test, mở merge request nhỏ.
  5. Tuỳ chọn refactor thêm cho sạch hoặc cho nhanh (có số đo).

4. Đặt tên

Ý chính: tên là tài liệu duy nhất ai đọc code cũng đọc (Phil Karlton: hai việc khó nhất là invalidate cache và đặt tên). Tên tốt nói vai trò hoặc hành động, phân biệt bằng thuộc tính, và dùng một từ cho một khái niệm.

  • Có nghĩa: class là danh từ chỉ vai trò (DiscountCalculator, không phải DiscountManager), method là động từ (reserveSeat).
  • Phân biệt bằng thuộc tính: Cache với LocalCache, RemoteCache; CacheImpl hay ICache không nói khác gì.
  • Tránh tên mơ hồ: data, info, tmp, msg1/msg2 (có lẽ là requestMessage/replyMessage).
  • Đọc thành tiếng được: generationTimestamp, không phải genymdhms.
  • Không tiền tố kiểu: strName, listUsers thành sai khi kiểu đổi. Viết users, ordersById.
  • Nhất quán từ vựng: repository dùng find thì chỗ khác đừng get hay fetch cùng ý.

Bài tập trên slide: scope và isScope

Ý chính: slide cho boolean isScope = checkScope(); là đúng, boolean scope = ... là sai. is giúp đọc ra boolean, nhưng vẫn chưa nói scope cái gì và true nghĩa là gì.

5. Hàm

Ý chính: hàm đọc từ trên xuống như kể chuyện, làm một việc, không vừa đổi trạng thái vừa trả lời. Con số “40 dòng, 3 tham số” chỉ là heuristic.

  • Stepdown rule: hàm cấp cao ở trên, hàm nó gọi nằm ngay dưới; người đọc dừng ở mức chi tiết mình cần.
  • Làm một việc = một lý do để thay đổi. Không có side effect bất ngờ: isValidPassword không được tiện tay tạo session.
  • CQS (Command Query Separation): method hoặc làm (command, trả void), hoặc trả lời (query, không đổi trạng thái), không cả hai.
// Vi phạm CQS: tên nghe như query nhưng lại trừ kho
boolean checkAndReserve(String sku, int qty) {
    int left = stock.getOrDefault(sku, 0);
    if (left < qty) return false;
    stock.put(sku, left - qty);
    return true;
}

// Tách ra: query không đổi gì, command thất bại thì ném lỗi có bối cảnh
boolean hasStock(String sku, int qty) {
    return stock.getOrDefault(sku, 0) >= qty;
}

void reserve(String sku, int qty) {
    int left = stock.getOrDefault(sku, 0);
    if (left < qty) {
        throw new IllegalStateException("Not enough stock for " + sku + ": need " + qty + ", have " + left);
    }
    stock.put(sku, left - qty);
}

reserve vẫn tự kiểm tra lại, vì hai thread có thể cùng thấy hasStock trả true. Cũng vì thế Map.putIfAbsent, AtomicInteger.incrementAndGet, Queue.poll cố ý gộp query và command: tách ra là có race condition giữa lúc hỏi và lúc làm. CQS là quy tắc cho code nghiệp vụ, không cho primitive đồng thời.

  • Nhỏ: khoá học nói khoảng 40 dòng, một switch, tối đa 3 tham số. Hàm 60 dòng tuần tự không lồng có thể dễ đọc hơn năm hàm 12 dòng nhảy qua lại. Dấu hiệu thật cần tách: comment // bước 2 chia khúc, hoặc lồng sâu. Hơn 3 tham số thì gom thành record.
  • Ưu tiên hàm thuần (cùng input cùng output, không đọc đồng hồ, không gọi database): test bằng một assertEquals, chạy song song an toàn. Mẫu: “lõi thuần, vỏ có I/O”.
  • Tránh lồng sâu, cả if lẫn callback (mục 8).
  • DRY là về tri thức, không về ký tự: hai đoạn giống nhau nhưng đổi vì hai lý do khác nhau thì không phải trùng lặp.

6. Class

Ý chính: class nhỏ, một trách nhiệm; thử đặt tên là cách kiểm tra rẻ nhất. Thêm biến thể mới bằng class anh em, không bằng kế thừa class cũ.

SRP qua cái tên. Tên tự nhiên nhất là OrderManager, OrderHelper hoặc cần chữ “And” thì class ôm nhiều việc. Class A trên slide (hằng số DOMAIN, PORT, field static String name thay đổi được, method1() đến method4()) không đặt được tên tốt vì không có trách nhiệm rõ.

Open-Closed: tổ chức để đón thay đổi. Slide: class A đang sinh SELECT, giờ cần sinh UPDATE; cách giải đề xuất là B extends A.

Trong Java 21, cách gọn nhất là sealed interface (interface chỉ cho phép một danh sách class cài đặt cố định) cộng record:

sealed interface SqlStatement permits Select, Update {
    String toSql();
}

record Select(String table, List<String> columns, String where) implements SqlStatement {
    public String toSql() {
        String sql = "SELECT " + String.join(", ", columns) + " FROM " + table;
        return where == null ? sql : sql + " WHERE " + where;
    }
}

record Update(String table, Map<String, String> assignments, String where) implements SqlStatement {
    Update {
        if (where == null || where.isBlank()) {
            throw new IllegalArgumentException("UPDATE without WHERE is not allowed");
        }
    }
    public String toSql() {
        String set = assignments.entrySet().stream()
                .map(e -> e.getKey() + " = " + e.getValue())
                .collect(Collectors.joining(", "));
        return "UPDATE " + table + " SET " + set + " WHERE " + where;
    }
}

Update tự từ chối thiếu WHERE trong compact constructor. Rẽ nhánh theo loại thì dùng switch (statement) { case Select s -> ...; case Update u -> ...; }, không cần default. Thêm Delete thì compiler báo lỗi ở mọi switch chưa xử lý: change amplification có compiler chỉ đường, thay vì unknown unknowns.

Sealed hay interface mở: expression problem

7. Giữ một mức trừu tượng trong mỗi hàm

Ý chính: mọi câu lệnh trong một hàm nên ở cùng một mức trừu tượng (SLAP, Single Level of Abstraction Principle). Hàm chính nói bằng ngôn ngữ nghiệp vụ, chi tiết kỹ thuật nằm một tầng dưới.

Slide minh hoạ bằng hàm createPizza dài: tạo đế, chọn topping theo loại, vòng lặp chờ lò đủ nóng, nướng, đóng hộp, cắt bánh, tất cả một khối. Sau refactor, hàm chính còn ba bước:

static Pizza createPizza(Order order) {
    Pizza pizza = prepare(order);
    bake(pizza);
    box(pizza);
    return pizza;
}

static Pizza prepare(Order order) {
    Pizza pizza = new Pizza(order.size());
    pizza.toppings = toppingsFor(order.kind());   // switch theo VEG/MEAT
    return pizza;
}

Nhiệt độ và vòng chờ lò nằm trong bake. Giống mục lục sách: ghi tên chương, không chép nội dung chương vào.

8. Làm phẳng luồng điều khiển

Ý chính: chặn trường hợp biên ở đầu hàm, và tách phần rẽ nhánh ra hàm phụ.

Guard clause: xử lý trường hợp biên trước

Ý chính: guard clause là kiểm tra ở đầu hàm rồi return hoặc ném exception ngay, thay cho chuỗi if / else if / else giấu happy path trong else.

Hàm createBooking trên slide, viết lại bằng Java và sửa vài lỗi còn sót:

// Trước: happy path bị đẩy vào else, lỗi chỉ được in ra rồi trả null
public Booking createBooking(User user, Seat seat) {
    if (user.getStatus() == false) {
        System.out.println("User is not active");
    } else if (seat.isBooked() == true) {
        System.out.println("Seat is already booked");
    } else {
        return new Booking(user.id(), seat.number());
    }
    return null;
}

// Sau: guard clause, exception theo domain, happy path ở cuối không thụt lề
public Booking createBooking(User user, Seat seat) {
    if (!user.active()) throw new UserInactiveException(user.id());
    if (seat.booked()) throw new SeatAlreadyBookedException(seat.number());
    return new Booking(user.id(), seat.number());
}

Giảm số cấu trúc người đọc phải giữ trong đầu

Ý chính: tách phần rẽ nhánh ra hàm phụ có tên. Tổng không giảm nhiều, nhưng mỗi chỗ người đọc nhìn vào nhỏ hơn.

Hai kỹ thuật nữa: tách điều kiện dài thành method có tên (isEligibleForRefund(order)), thay chuỗi if / else if trên một biến bằng switch biểu thức. Refactor luồng điều khiển nên luôn kèm phép so sánh tự động cũ với mới.

Ví dụ từ Google Testing Blog: vòng lặp phòng khách sạn

Slide lấy từ bài “Write Clean Code to Reduce Cognitive Load” (Google Testing Blog, 2023): vòng while chứa if / else if và một if có break (5 cấu trúc, 9 cạnh) khó nhớ hơn vòng lặp gọi một hàm phụ (3 cấu trúc, 5 cạnh) cộng hàm phụ (2 cấu trúc, 4 cạnh). Ví dụ tương tự:

// Trước: một vòng lặp vừa chọn cách phục vụ, vừa xử lý cảnh báo
for (Room r : rooms) {
    if (!r.occupied()) continue;
    if (r.vip()) {
        log.add("warm");
    } else if (r.guestOnPhone()) {
        log.add("quiet");
    }
    if (r.hasAllergyRisk()) {
        log.add("alert");
        break;
    }
}

// Sau: vòng lặp kể câu chuyện, hàm phụ giữ phần chọn lựa
for (Room room : rooms) {
    if (!room.occupied()) continue;
    comfortAction(room).ifPresent(log::add);
    if (room.hasAllergyRisk()) {
        log.add("alert");
        break;
    }
}

static Optional<String> comfortAction(Room room) {
    if (room.vip()) return Optional.of("warm");
    if (room.guestOnPhone()) return Optional.of("quiet");
    return Optional.empty();
}

Mình chạy hai phiên bản trên 2.000 bộ phòng sinh ngẫu nhiên và so sánh: giống nhau hoàn toàn.

Bài tập

Toàn bộ code ở mục 5 đến 8 và hai bài tập đã được chạy với JDK 21 kèm các phép kiểm tra tự động.

Bài 1: Đặt lại tên

Đề (tự đặt): đổi tên đoạn sau để không cần comment.

// trả về list user active đã login trong d ngày
List<User> get(List<User> l, int d) {
    List<User> r = new ArrayList<>();
    for (User u : l) if (u.getS() == 1 && u.getLl().isAfter(LocalDate.now().minusDays(d))) r.add(u);
    return r;
}
Lời giải Bài 1
List<User> activeUsersLoggedInWithin(List<User> users, Duration window, LocalDate today) {
    LocalDate cutoff = today.minusDays(window.toDays());
    return users.stream()
            .filter(User::isActive)
            .filter(user -> user.lastLoginDate().isAfter(cutoff))
            .toList();
}

getS() == 1 (magic number) thành isActive(), int d thành Duration để kiểu tự nói đơn vị, LocalDate.now() thành tham số today để hàm thuần và test được. Comment trở nên thừa.

Bài 2: Làm phẳng hàm tính phí vận chuyển

Đề: hàm sau lồng bốn tầng và trả -1 khi giỏ hàng null. Viết lại cho phẳng, giữ nguyên kết quả với input hợp lệ.

static long feeNested(Cart c) {
    long fee = 0;
    if (c != null) {
        if (c.country().equals("VN")) {
            if (c.subtotal() >= 500_000) {
                fee = 0;
            } else {
                if (c.member()) fee = 15_000; else fee = 30_000;
            }
            if (c.express()) fee = fee + 20_000;
        } else {
            fee = 200_000;
            if (c.express()) fee = fee + 100_000;
        }
    } else {
        fee = -1;
    }
    return fee;
}
Lời giải Bài 2
static final long FREE_SHIPPING_THRESHOLD = 500_000;

static long shippingFee(Cart cart) {
    Objects.requireNonNull(cart, "cart");
    if (!cart.country().equals("VN")) return 200_000 + (cart.express() ? 100_000 : 0);
    return domesticBaseFee(cart) + (cart.express() ? 20_000 : 0);
}

static long domesticBaseFee(Cart cart) {
    if (cart.subtotal() >= FREE_SHIPPING_THRESHOLD) return 0;
    return cart.member() ? 15_000 : 30_000;
}

Mình chạy cả hai hàm trên 40 tổ hợp (5 mức subtotal quanh ngưỡng, 2 quốc gia, thành viên hay không, express hay không): giống hệt.

Có một thay đổi hành vi có chủ đích: giỏ null giờ ném NullPointerException thay vì trả -1. Giá trị đặc biệt -1 cho phí là bug chờ xảy ra (ai đó cộng nó vào tổng tiền). Thay đổi kiểu này phải nêu rõ trong PR và tách commit riêng, không lẫn vào commit “chỉ refactor”.

Ghi nhớ

  • Giải thích được vì sao code bẩn chỉ rẻ trong vài tuần đầu, và bốn chữ “-able”.
  • Kể được ba triệu chứng của độ phức tạp và vì sao thiếu nhất quán sinh ra unknown unknowns.
  • Biết đặt tên boolean theo câu hỏi, và vì sao checkX() trả boolean là tên tồi.
  • Giải thích được CQS và vì sao putIfAbsent cố ý vi phạm nó.
  • Biết khi nào gộp code trùng (rule of three, hằng số gộp ngay) và khi nào dùng sealed interface thay vì kế thừa.

Câu hỏi phỏng vấn

Junior

Clean code là gì? Vì sao doanh nghiệp nên quan tâm?

Là code dễ hiểu và dễ thay đổi; doanh nghiệp quan tâm vì nó giữ chi phí mỗi thay đổi thấp.

Code bẩn rẻ vài tuần đầu, sau đó mỗi tính năng tốn hơn rất nhanh, bug nhiều hơn, ra thị trường chậm hơn. Mục tiêu là giảm công sức con người để xây và bảo trì hệ thống.

Đặt tên biến boolean thế nào cho tốt?

Theo câu hỏi mà giá trị trả lời, thường với is, has, can: emailVerified, hasScope, canRefund.

Tránh tên trung tính như flag, tránh phủ định (notDisabled). Method trả boolean không nên tên checkX() vì không rõ true nghĩa là gì.

Guard clause là gì?

Kiểm tra trường hợp biên ở đầu hàm và return hoặc ném exception ngay, để happy path nằm cuối hàm không thụt lề.

Nó thay chuỗi if / else if / else lồng nhau và làm hàm đọc từ trên xuống dễ hơn.

Mid

Command Query Separation là gì, có ngoại lệ nào không?

Một method hoặc đổi trạng thái (command), hoặc trả thông tin (query), không cả hai; có ngoại lệ cho thao tác nguyên tử.

Gọi query bao nhiêu lần cũng an toàn. Ngoại lệ có chủ đích là putIfAbsent, incrementAndGet, poll: tách ra sẽ có race condition giữa lúc hỏi và lúc làm.

Ba triệu chứng của độ phức tạp theo Ousterhout là gì?

Change amplification, cognitive load và unknown unknowns (tệ nhất).

Change amplification: thay đổi đơn giản phải sửa nhiều nơi. Cognitive load: phải nhớ nhiều thứ mới sửa an toàn. Unknown unknowns: không biết mình cần biết gì. Nguyên nhân là phụ thuộc và sự mơ hồ; thiếu nhất quán là nguồn chính của unknown unknowns.

DRY có phải lúc nào cũng đúng?

Không. DRY là về tri thức chứ không về ký tự.

Hai đoạn giống nhau nhưng đổi vì hai lý do khác nhau thì không nên gộp; gộp sớm dễ sinh abstraction sai đầy cờ boolean. Thực tế dùng rule of three, còn quy tắc nghiệp vụ và hằng số thì gộp ngay.

Làm sao biết một class vi phạm SRP?

Thử đặt tên: tên tự nhiên nhất là Manager, Helper hoặc cần chữ “And” thì class làm nhiều việc.

Dấu hiệu khác: bị sửa vì nhiều lý do không liên quan, test phải mock quá nhiều, các nhóm method dùng các nhóm field rời nhau.

Senior

Trên slide, để thêm câu lệnh UPDATE người ta cho class mới kế thừa class sinh SELECT. Bạn góp ý thế nào?

Kế thừa sai nghĩa (UPDATE không phải một loại SELECT) và phá Liskov; nên dùng các class anh em dưới một abstraction chung.

Chỗ nhận bộ sinh SELECT có thể nhận phải object sinh UPDATE, class con mang theo field không dùng. Trong Java 21 là sealed interface SqlStatement với các record và switch theo pattern để compiler kiểm tra đủ trường hợp.

Cognitive complexity khác cyclomatic complexity thế nào, bạn dùng chúng ra sao?

Cyclomatic đếm đường đi độc lập (ước số test); cognitive cộng thêm theo độ sâu lồng nên phản ánh độ khó đọc tốt hơn.

Cyclomatic không phân biệt switch phẳng với if lồng nhau. Mình đặt ngưỡng cognitive complexity (Sonar mặc định 15 cho Java) làm quality gate cho code mới, không bắt sửa toàn bộ code cũ một lúc.

Bạn đưa clean code vào một team có codebase cũ thế nào?

Không viết lại; cải thiện dần, có công cụ và test bảo vệ.

Đưa vài quy ước vào công cụ (formatter, quality gate chỉ áp cho code mới), để lại code sạch hơn một chút mỗi lần chạm vào, refactor kèm test đặc tả hành vi và tách commit refactor khỏi commit đổi hành vi. Ưu tiên vùng thay đổi nhiều nhất theo lịch sử git, nơi độ phức tạp tốn tiền nhất.

Từ vựng tiếng Anh

Term Phát âm Nghĩa Ví dụ câu tiếng Anh dùng trong phỏng vấn
code smell /kəʊd smel/ dấu hiệu code có vấn đề “A boolean parameter that switches behaviour is a code smell.”
cognitive load /ˈkɒɡnətɪv ləʊd/ gánh nặng nhận thức “Deep nesting adds cognitive load.”
change amplification /tʃeɪndʒ ˌæmplɪfɪˈkeɪʃn/ một thay đổi kéo theo sửa nhiều nơi “Hard-coding the threshold in three places caused change amplification.”
unknown unknowns /ʌnˈnəʊn ʌnˈnəʊnz/ điều không biết là mình không biết “Inconsistent conventions create unknown unknowns.”
guard clause /ɡɑːd klɔːz/ mệnh đề chặn đầu hàm “Guard clauses keep the happy path out of an else block.”
pure function /pjʊə ˈfʌŋkʃn/ hàm thuần “Pricing lives in pure functions, so the tests need no mocks.”
command-query separation /kəˈmɑːnd ˈkwɪəri ˌsepəˈreɪʃn/ tách lệnh và truy vấn “This method breaks command-query separation: it reads like a check but mutates stock.”
wrong abstraction /rɒŋ æbˈstrækʃn/ trừu tượng hoá sai “Duplication is cheaper than the wrong abstraction.”
over-engineering /ˌəʊvər ˌendʒɪˈnɪərɪŋ/ thiết kế quá mức cần “An interface with one implementation ‘just in case’ is over-engineering.”
sealed interface /siːld ˈɪntəfeɪs/ interface giới hạn lớp cài đặt “A sealed interface lets the compiler check that my switch covers every case.”

Ghi chép dựa trên khoá Advanced Backend (Ronin Engineer), viết lại theo cách hiểu của mình.