Ruby Coding Convention (Phần 3)

Ở phần hai, tôi đã giới thiệu về cú pháp trong Ruby, làm sao để các câu lệnh điều kiện, vòng lặp, block, methods … dễ hiểu, dễ đọc hơn, có qui tắc chung với cả team. Phần tiếp theo sẽ đề cập tới cách đặt tên và cách comment sao cho dể hiểu.

Naming

• Tất cả các cách đặt tên biến, tên hàm cần được viết bằng tiếng Anh, và chỉ sử dụng các kí tự ascii
• Đặt tên biến, tên hàm bằng chữ viết thường, cách nhau bởi dấu _
  
  # good :some_symbol def some_method ... end

  1 2 3 4 5 6

  # good :some_symbol   def some_method   ... end

• Đặt tên Class bằng cách viết hoa các chữ cái đầu tiên ClassName
• Đặt tên hằng số bằng các chữ viết hoa toàn bộ, cách nhau bởi dấu _
  
  # bad SomeConst = 5 # good SOME_CONST = 5

  1 2 3 4 5

  # bad SomeConst = 5   # good SOME_CONST = 5

• Nhưng hàm trả về giá trị boolean cần được kết thúc bởi dấu ?. Ví dụ Array#empty?
• Đối với những hàm có thể gây ra hậu quả gì đó (ví dụ như thay đổi đối tượng self) nên được kết thúc với dấu !
  
  # bad - Nếu đây chỉ là hàm update thông thường class Person def update! end end # good class Person def update end end # good class Person # phân biệt với hàm update ở dưới. Trong hàm này có xử lí 1 tác vụ gì khác def update! end def update end end

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

  # bad - Nếu đây chỉ là hàm update thông thường   class Person     def update!     end   end     # good   class Person     def update     end   end     # good   class Person     # phân biệt với hàm update ở dưới. Trong hàm này có xử lí 1 tác vụ gì khác     def update!     end       def update     end   end

• Sử dụng flat_map thay cho map ... .flatten
  
  # bad all_songs = users.map(&:songs).flatten.uniq # good all_songs = users.flat_map(&:songs).uniq

  1 2 3 4 5

  # bad   all_songs = users.map(&:songs).flatten.uniq     # good   all_songs = users.flat_map(&:songs).uniq

• Sử dụng reverse_each(Không tạo ra array mới) thay cho reverse.each
  
  # bad array.reverse.each { ... } # good array.reverse_each { ... }

  1 2 3 4 5

  # bad   array.reverse.each { ... }     # good   array.reverse_each { ... }

Comments

• Mỗi comment nên cách dấu # một dấu cách
• Tránh những comment không cần thiết
  
  count += 1 # tăng giá trị biến đếm lên 1

  1	count += 1 # tăng giá trị biến đếm lên 1

• Comment cũng cần được update. Những comment không được update nguy hiểm hơn cả không comment
• Tránh comment cho những đoạn code chưa được refactor, rườm rà. Hãy refactor trước để code có thể dễ hiểu.
• Đối với những comment dài, nên xuống dòng, và dòng dưới nên thụt vào 2 dấu cách
• Thêm TODO đối với những chức năng cần được bổ sung về sau
• Thêm FIXME đối với những chức năng cần được thay đổi, sửa
• Thêm OPTIMIZE đối với những đoạn code chưa tối ưu làm ảnh hưởng tới performance
• Thêm HACK đối với những đoạn code vi phạm practices và cần được refactor loại bỏ
• Thêm REVIEW đối với những chức năng cần được xác nhận lại