16: Bàn về việc comment code

Trong lớp học lập trình đầu tiên của tôi ở đại học, giáo viên đã phát cho mỗi người hai tờ giấy lập trình (coding sheet) sau đó ông ấy viết bài tập lên bảng rồi rời khỏi phòng, bài tập như sau : “Viết một chương trình nhập vào 10 điểm của trò chơi bowling và tính điểm trung bình cộng”. Bài toán này có thể khó tới mức nào? Tôi không nhớ cách giải là gì, nhưng tôi chắc nó có sử dụng vòng lặp FOR/NEXT và tổng cộng không quá 15 dòng. Mỗi tờ Coding Sheet chỉ có thể chứa khoảng 70 dòng — Dành cho những ai đang đọc cái này, đúng vậy, chúng tôi đã từng viết code trên giấy rất lâu trước khi thực sự đưa chúng vào máy tính. Tôi đã rất bối rối tại sao giáo viên lại đưa cho chúng tôi 2 tờ trong khi thuật toán chưa tới 15 dòng code. Vì chữ viết của tôi không được đẹp nên tôi đã sử dụng tờ coding sheet còn lại để copy bài code ra một cách rõ ràng hơn với hy vọng có thêm một vài điểm cộng về phong cách.

Tôi đã rất ngạc nhiên khi nhận lại bài tập của mình vào đầu giờ của tiết học tiếp theo, điểm số của tôi chỉ vừa đủ để qua môn. (Nó đã trở thành điềm báo với tôi về khoảng thời gian còn lại ở đại học.) Nguệch ngoạc phía trên bài code mà tôi đã sao chép là dòng chữ “Không có comments ?” (“No comment?”)

Việc giáo viên và tôi đều biết nhiệm vụ của chương trình là gì vẫn chưa đủ. Một phần, mục đích của bài tập này đã dạy tôi rằng code của tôi phải có thể “tự giải thích” với các lập trình viên khác chức năng của nó. Đó là một bài học mà tôi không bao giờ quên.

Comment không phải là xấu. Chúng cần thiết cho những bài lập trình như cấu trúc rẽ nhánh hoặc cấu trúc lặp. Hầu hết các ngôn ngữ hiện đại đều có công cụ gần giống với Javadoc có thể phân tích các comment đã được định dạng một cách chính xác để tự động xây dựng một thư mục API. Đây là một khởi đầu tốt, nhưng chưa đủ. Trong code của bạn nên có những giải thích về chức năng mà nó đang thực hiện. Theo như một câu ngạn ngữ cũ :”Nếu như nó khó để viết, thì cũng sẽ khó để đọc”. Nếu bạn code như vậy thì bạn không những gây khó khăn cho khách hàng, cấp trên hay đồng nghiệp, mà còn gây không ít trở ngại cho bạn sau này.

Mặt khác, bạn không nên lạm dụng comment. Đảm bảo rằng comment làm rõ code của bạn chứ không phải làm cho nó trở nên khó hiểu. Hãy viết những comment thích hợp để giải thích mục đích của code là gì. ## comment tiêu đề (header comment) bạn nên đưa ra đầy đủ thông tin để bất kỳ lập trình viên nào cũng đều có thể sử dụng đoạn code của bạn mà không cần đọc nó, trong khi đó, các inline comment nên hỗ trợ tốt các developer tiếp theo trong việc sửa chữa hoặc mở rộng code.

Trong một lần bàn bạc về công việc, tôi đã không đồng tình với một quyết định về bản thiết kế của cấp trên. Cũng như cách mà các lập trình viên nghiệp dư thường làm, tôi đã copy đoạn văn bản từ email 📮 hướng dẫn sử dụng bản thiết kế của họ vào phần header comment của file project của mình mặc dù trước đó đã tỏ ra sự bất đồng với cấp trên, điều đó khá là xấu hổ. Hóa ra ngay sau khi tôi bàn giao lại sản phẩm, thì các quản lý của shop đã review lại code, tôi nhận ra việc thêm các hướng dẫn đó vào phần header comment đã thực sự cứu tôi. Và đó cũng là lần đầu tiên tôi biết đến thuật ngữ career-limiting move (Hành động hoặc lỗi lầm gây trở ngại trong việc thăng tiến sự nghiệp).