Nên viết Comment code như thế nào?

Bài viết gần đây

OFFER ĐẦU TIÊN CỦA CHƯƠNG TRÌNH RTEP – CHẠM ĐẾN MỤC TIÊU ĐẶT CHÂN ĐẾN XỬ SỞ HOA ANH ĐÀO

Tháng 8 vừa qua, Chương trình đào tạo kỹ sư CNTT tài năng Việt Nhật (RTEP) nhận được tin...

Ở đây có Chương trình RTEP sẵn sàng tuyển sinh khóa K3

Trong chuỗi các hoạt động Rikkeisoft tham gia tại “Tuần lễ việc làm DTU 2022”, chương trình đào tạo...

Học kỳ mới đã tới, khai giảng lớp đào tạo tiếng Nhật IT thôi!

Ngày 1/3/2022, chương trình RTEP đã Khai giảng lớp Đào tạo tiếng Nhật IT dành cho các RTEP-er K1...

Phá tan rào cản, RTEP K1 và K2 hoàn thành kỳ học thử thách

Vượt qua những trở ngại và thách thức lớn trong giai đoạn dịch bệnh Covid 19, các học viên...

TUỔI TRẺ NÀY MÌNH CÙNG NHAU ….

Chủ nhật tuần vừa qua, tất cả các học viên RTEP đã có một chuyến Teambuilding đầu năm đáng...

Viết comment vào source code như thế nào cho hiệu quả, tránh thiếu cũng như dư thừa không cần thiết? Với mong muốn chia sẻ về cách xác định xem trường hợp nào cần viết và cách thức viết comment, bài viết dưới đây sẽ giới thiệu về các quy tắc và lưu ý khi viết comment.

Mục đích của viết comment code nhằm truyền đạt ý đồ của người viết code cho người đọc code. Mỗi khi viết ra một hàm hay một class nào đó, người viết code sẽ có những suy nghĩ, nhận định của bản thân với những dòng code được viết ra. Những suy nghĩ đó sẽ giúp cho việc đọc hiểu của người tiếp nối thuận lợi hơn nếu được truyền đạt một cách ngắn gọn, dễ hiểu và đầy đủ. Ở bài viết này, chúng ta sẽ tìm hiểu về các mục sau khi viết comment code:

  • Những trường hợp không cần viết comment code
  • Ghi lại những suy nghĩ của bản thân khi đang viết code
  • Suy nghĩ ở vị trí của người đọc code để hiểu mình cần comment nội dung gì

I. Những trường hợp không cần viết comment

Chúng ta hãy xem xét ví dụ dưới đây:

Như các bạn đã thấy ở trên, những comment đó không cung cấp thêm thông tin giúp người đọc code đọc nhanh hơn. Vì vậy cần lưu ý, không comment vào các nội dung mà chỉ cần đọc code là có thể hiểu ngay được.

I.1. Không comment chỉ để giữ quy tắc

Có những nơi quy định bắt buộc phải viết comment đầy đủ cho mỗi function hay class được viết. Nên có những trường hợp như sau:

I.2. Hãy sửa nếu tên không diễn đạt đủ ý nghĩa thay vì comment vào chỉ để giải thích

Nếu nhìn qua tên thì ai cũng nghĩ ngay rằng Delete Registry là hàm phải rất cẩn trọng khi sử dụng vì dùng không cẩn thận có thể xóa mất Registry, tuy nhiên đọc comment thì nó không gây ảnh hưởng đến Registry. Thay vì comment vào như thế, chúng ta nên lấy một cái tên đẹp hơn cho function này

II. Ghi lại những suy nghĩ của bản thân khi đang viết code

II.1. Comment tổng quan

Với mỗi class hay function phức tạp chúng ta nên viết giới thiệu hay thuyết minh tổng quan cho chúng để người đọc có cái nhìn bao quát và đi nhanh hơn trong quá trình đọc chi tiết. Những vấn đề trong source code cần giải quyết. Ví dụ như:

II.2. Comment vào những điểm còn khúc mắc và chưa được thực hiện

Những phần này có cú pháp phần mở đầu phân theo từng mục đích:

TODO: Để sau làm

FIXME: Hiện tại đang có lỗi

HACK: Cách làm chưa được tốt lắm, cần cải tiến

XXX: Nguy hiểm, có vấn đề lớn

Tuỳ từng tổ chức mà có thể thay đổi cú pháp cho phù hợp, ví dụ như vấn đề lớn cần làm thì viết HOA toàn bộ “TODO:” , vấn đề nhỏ thì viết thường “todo:”

II.3. Comment cho hằng số

Với hằng số, chúng ta nên comment để người đọc hiểu tại sao nên chọn giá trị đó. Khi ấy việc chỉnh sửa sẽ nhanh và dễ dàng hơn rất nhiều.

III. Comment code đứng ở lập trường của người đọc

Một số lưu ý khi thực hiện comment code tạo điều kiện cho người đọc code dễ dàng tiếp nhận thông tin hơn:

– Dự tính trước các thắc mắc người đọc gặp

– Thông báo trước các cạm bẫy có thể gặp phải gây hiểu lầm trong quá trình đọc

– Viết comment tổng quan ngắn gọn, đảm bảo đủ ý nghĩa

IV. Vượt qua trở ngại khi bắt đầu viết comment code

03 bước để có một comment code nhanh chóng và hiệu quả:

  • Viết ra ngay suy nghĩ trong đầu
  • Xem lại câu cú xem cần sửa chữa chỗ nào
  • Tiến hành sửa
  • Tổng kết

Trên đây là giới thiệu cơ bản về cách viết những comment code tối ưu hiệu quả. Hy vọng sẽ giúp các bạn áp dụng vào công việc của mình tốt hơn.

Nguồn: Viblo

Góc Nhật Bản

Những điều cần biết về kì thi năng lực tiếng Nhật JLPT

JLPT là gì? Kỳ thi năng lực tiếng Nhật có tên tiếng Nhật 日本語能力試験(にほんごのうりょくしけん) tiếng Anh: "Japanese Language Proficiency Test" - JLPT) là kì...

Hanami – Độc đáo lễ hội hoa anh đào Nhật Bản

Hoa anh đào (桜, sakura) được xem như là quốc hoa (không chính thức) của đất nước mặt trời mọc. Hàng năm, các ngôi...

Bí quyết đánh đổ bài thi JLPT

Bất kỳ ai khi theo học tiếng Nhật Nhật cũng biết về bài thi JLPT. Đây là bài thi năng lực tiếng Nhật được...

Nét đặc trưng trong văn hóa chào hỏi của người Nhật Bản

Đối với người Nhật Bản, văn hóa chào hỏi chính là một nét văn hóa đặc trưng dần trở thành phong cách của mỗi...

Truyền nghề

BÍ KÍP “NHỜ VẢ” CHO CÁC LẬP TRÌNH VIÊN ÍT KINH NGHIỆM TẠI NƠI CÔNG SỞ

Khi mới chập chững làm quen với công việc của một lập trình viên, chắc chắn bạn sẽ thường xuyên gặp nhiều vướng mắc...

DÙNG EMAIL ĐỈNH CAO, ĐỪNG MẮC NHỮNG SAI LẦM SAU

Hiện nay, email vẫn là phương tiện chủ yếu giúp chúng ta kết nối với mọi người, trong cả việc công lẫn việc cá...

19 Sai Lầm Của Lập Trình Viên

Sưu tầm nhiều sách, tải nhiều video học lập trình nhưng bao giờ đọc và học nghiêm túc Hiện nay, sách Ebook quá nhiều,...

Lập trình viên có phải là những anh hùng bàn phím?

LÀM LẬP TRÌNH VIÊN LÀ GẮN LIỀN VỚI MÁY TÍNH! Đây là một định kiến mà hầu hết mọi người đều nghĩ đến khi nhắc...