Coding Standards and Guidelines

Định nghĩa

• Coding Standards and Guidelines là những quy chuẩn về phong cách lập trình được định nghĩa rõ ràng và tiêu chuẩn hóa mà các tổ chức phát triển phần mềm yêu cầu lập trình viên tuân thủ.
• Các tổ chức thường xây dựng bộ quy tắc riêng dựa trên:
  • Đặc thù của tổ chức
  • Loại phần mềm phát triển
  • Ngôn ngữ lập trình sử dụng
• Việc tuân thủ các chuẩn này là bắt buộc, code không đạt chuẩn có thể bị từ chối trong quá trình review.

Mục đích

1. Tính nhất quán (Uniformity):

   • Đảm bảo code có giao diện đồng nhất dù được viết bởi nhiều kỹ sư khác nhau
   • Ví dụ: Cùng một quy tắc đặt tên biến trên toàn bộ dự án

2. Khả năng đọc và bảo trì (Readability & Maintainability):

   • Giảm 40-60% thời gian đọc hiểu code (theo nghiên cứu của IBM)
   • Dễ dàng cập nhật, sửa chữa khi có yêu cầu thay đổi

3. Tái sử dụng code (Reusability):

   • Code được chuẩn hóa dễ tích hợp vào các module khác
   • Giảm 30% thời gian phát triển tính năng mới (theo Microsoft Research)

4. Chất lượng code:

   • Giảm 15-20% lỗi tiềm ẩn (NASA study)
   • Dễ phát hiện lỗi thông qua code review

Tiêu chuẩn trong Kỹ thuật Phần mềm

1. Biến toàn cục (Global Variables)

• Hạn chế tối đa việc sử dụng
• Chỉ dùng cho các hằng số cấu hình hệ thống
• Phải có tiền tố g_ (ví dụ: g_systemConfig)

2. Tiêu đề module (Module Headers)

Để dễ hiểu và bảo trì code tốt hơn, phần header (tiêu đề) của các module (mô-đun) khác nhau nên tuân theo một định dạng và thông tin tiêu chuẩn. Định dạng này thường bao gồm:

• Tên của module.
• Ngày tạo module.
• Tác giả của module.
• Lịch sử sửa đổi (Modification history).
• Tóm tắt về chức năng của module (Synopsis of the module).
• Các function (hàm) được hỗ trợ trong module cùng với các tham số đầu vào (input parameters) và đầu ra (output parameters).
• Các global variable (biến toàn cục) được truy cập hoặc sửa đổi bởi module

"""
Module: user_authentication.py
Created: 2023-10-15
Author: Nguyen Van A
Modification History:
- 2023-10-20: Fixed login security issue
Synopsis: Handles user authentication and session management
Functions: - login(username, password) -> (bool, session_token) - logout(session_token) -> bool
Global Variables Accessed: - g_max_login_attempts
"""

3. Quy tắc đặt tên (Naming Conventions)

• Tên biến có ý nghĩa và dễ hiểu giúp người khác hiểu được mục đích sử dụng.
• Local variable nên được đặt tên theo kiểu camel case bắt đầu bằng chữ thường (ví dụ: localData), trong khi tên Global variable nên bắt đầu bằng chữ hoa (ví dụ: GlobalData). Tên Constant nên được viết bằng tất cả chữ hoa (ví dụ: CONSDATA).
• Nên tránh sử dụng chữ số trong tên biến.
• Tên của function nên được viết theo kiểu camel case bắt đầu bằng chữ thường.
• Tên của function phải mô tả rõ ràng và ngắn gọn lý do sử dụng function đó.

4. Thụt lề (Indentation)

• Phải có một khoảng trắng sau dấu phẩy giữa hai đối số của function.

• Mỗi nested block (khối lệnh lồng nhau) nên được thụt lề và cách đều.

• Phải có Indentation thích hợp ở đầu và cuối mỗi block (khối lệnh) trong chương trình.

• Tất cả các dấu ngoặc nhọn nên bắt đầu trên một dòng mới và code sau dấu ngoặc nhọn kết thúc cũng nên bắt đầu trên một dòng mới

• Sử dụng 2 hoặc 4 spaces (thống nhất trong toàn dự án)

• Ví dụ JavaScript:

function calculateTotal(items) { let total = 0; items.forEach((item) => { if (item.valid) { total += item.price * item.quantity; } }); return total;
}

5. Xử lý lỗi (Error Handling)

• Luôn trả về object error thống nhất:

interface ApiResponse { success: boolean; data?: any; error?: { code: string; message: string; };
}

Coding Guidelines trong Kỹ thuật Phần mềm

• Tránh sử dụng style code quá khó hiểu: Code nên dễ hiểu. Code phức tạp gây khó khăn và tốn kém cho việc bảo trì và debugging.
• Tránh sử dụng một định danh (identifier) cho nhiều mục đích: Mỗi biến nên được đặt một tên mô tả và có ý nghĩa, thể hiện lý do sử dụng nó. Việc sử dụng một identifier cho nhiều mục đích có thể gây nhầm lẫn và khó khăn cho việc phát triển sau này.
• Code nên được ghi chú đầy đủ (well documented): Code nên được comment (chú thích) đầy đủ để dễ hiểu. Chú thích về các câu lệnh làm tăng khả năng hiểu code.
• Độ dài của function không nên quá lớn: Các function dài rất khó hiểu. Do đó, các function nên đủ nhỏ để thực hiện các công việc nhỏ và các function dài nên được chia thành các function nhỏ hơn để hoàn thành các tác vụ nhỏ.
• Cố gắng không sử dụng lệnh GOTO: Lệnh GOTO làm cho chương trình trở nên phi cấu trúc, do đó làm giảm khả năng hiểu chương trình và gây khó khăn cho việc debugging

Linh hoạt áp dụng một số quy ước và các nguyên tắc sau

1. Nguyên tắc cơ bản

• KISS (Keep It Simple, Stupid): Code đơn giản, dễ hiểu
• DRY (Don't Repeat Yourself): Tránh trùng lặp code
• SOLID: Áp dụng 5 nguyên tắc thiết kế hướng đối tượng

2. Độ dài hàm (Function Length)

• Không quá 20 dòng code/hàm
• Nếu vượt quá, cần tách thành các hàm con
• Mỗi hàm chỉ làm một nhiệm vụ duy nhất

3. Comment và Documentation

• Sử dụng JSDoc hoặc JavaDoc
• Ví dụ:

/** * Calculates the area of a circle * @param radius - The radius of the circle * @returns The calculated area * @throws IllegalArgumentException if radius is negative */
public double calculateCircleArea(double radius) { if (radius < 0) { throw new IllegalArgumentException("Radius cannot be negative"); } return Math.PI * radius * radius;
}

4. Cấu trúc code

• Áp dụng Design Patterns phù hợp
• Sử dụng dependency injection
• Viết unit test cho mọi hàm quan trọng

Ưu điểm khi áp dụng

• Tăng hiệu quả của phần mềm và giảm thời gian phát triển.
• Giúp phát hiện lỗi ở giai đoạn sớm, giảm chi phí phát sinh cho dự án phần mềm.
• Nếu coding guidelines được duy trì đúng cách, code phần mềm sẽ tăng tính dễ đọc và dễ hiểu, từ đó giảm độ phức tạp của code.
• Giảm chi phí ẩn khi phát triển phần mềm

1. Hiệu quả kinh tế:

   • Giảm 15-25% chi phí bảo trì (Gartner)
   • Tiết kiệm 20% thời gian onboarding nhân sự mới

2. Chất lượng sản phẩm:

   • Giảm 30-40% defects trong giai đoạn testing
   • Tăng khả năng mở rộng hệ thống

3. Bảo mật:

   • Giảm 50% lỗ hổng bảo mật (OWASP)
   • Code review hiệu quả hơn

Công cụ hỗ trợ

Kết luận

Việc áp dụng Coding Standards và Guidelines mang lại lợi ích to lớn:

• Ngắn hạn: Giảm thời gian phát triển, dễ dàng collaboration
• Dài hạn: Dễ bảo trì, nâng cấp, giảm technical debt
• Tổ chức: Xây dựng văn hóa phát triển chuyên nghiệp

"Một giờ tiết kiệm trong thiết kế có thể tiết kiệm 10 giờ trong debug" - Steve McConnell