Lập trình C: Hướng dẫn lập tư liệu nội bộ


Đăng ký nhận thông báo về những video mới nhất

A. Tổng quát

1. Đừng đợi đến khi viết xong một chương trình mới lập tư liệu. Khi từng phần của hệ thống được hoàn tất, hãy viết chú thích về chúng.

2. Phải giả thiết rằng người đọc không biết về những gì chương trình sẽ thực hiện.

3. Hãy nhớ rằng một đoạn mã lệnh xem chừng trực quan trong khi bạn viết chương trình, có thể không phải như vậy đối với người đọc hoặc cho chính bạn sau này.

Vì vậy, hãy ghi chú thích vào tư liệu.

4. Tránh việc lạm dụng sử dụng kiểu ghi chú /* */. Kiểu ghi chú này thường khó phân biệt với câu lệnh, đặc biệt là nếu nó chứa nhiều dòng.

B. Nội dung

1. Bảo đảm rằng các chú thích là chính xác.

2. Cập nhật các chú thích mỗi khi có thay đổi trên các câu lệnh.

3. Hãy ngắn gọn nhưng đầy đủ.

4. Hãy ghi chú cho các tên biến mà nó không tự-giải-thích một cách đầy đủ.

5. Đừng tỏ ra trịnh thượng.

6. Đừng hài hước.

C. Các khối header

1. Mỗi khối header của tư liệu nên có một dấu phân ranh giới phân biệt trên đỉnh và đáy của nó để người đọc có thể nhìn lướt qua từ một cấu trúc này sang một cấu trúc khác.

2. Một khối header phải được đặt trước cấu trúc mà nó mô tả và nên có cùng độ sâu.

3. Mỗi tập tin mã nguồn nên chứa một khối header tư liệu cung cấp các thông tin cơ bản về nội dung và tác giả.

4. Khối header của tập tin chính trong chương trình của bạn (nghĩa là tập tin chứa hàm main) cũng nên bao gồm.

5. Loại tư liệu này có thể cung cấp hướng dẫn cơ bản của lập trình viên cho chương trình của bạn hoặc các lớp có thể sử dụng lại.

6. Mỗi lớp nên có một khối header trong đó, chứa các thông tin:

Author:
Date Created:
Date Last Modified:
Class Revision History:
Date Change:
Change:
Changed By:

7. Lưu ý rằng các ghi chú này có thể được sao chép từ một tư liệu khác hoặc từ đầu khối lệnh tương ứng.

8. Mỗi hàm nên có một khối header nhỏ để mô tả ý nghĩa của hàm. Nếu sử dụng một giải thuật phức tạp, cũng nên đưa vào một mô tả ngắn gọn về giải thuật để giúp cho mã lệnh của hàm dễ hiểu.

//Function Name: addStudent
//Author:
//Date Created:
//Date Last Modified:
//Description: Algorithm Description
//Parameters:
//Name:
//Type:
//Purpose:
//Name: String
//Mark: int
//Return Type: int
//Function Revision History:
//Date Change:
//Change:
//Changed By:
int addStudent(String name, int mark)
{ ..
.
}

D. Các ghi chú trong-dòng-lệnh

1. Sử dụng tư liệu trong-dòng-lệnh khi cần để mô tả thêm cho một quá trình xử lý.Đặt một ghi chú trên cùng một dòng với câu lệnh khi ghi chú đó chỉ áp dụng cho một dòng lệnh và có thể nằm gọn trên dòng đó. Nếu không thì, đặt ghi chú trên một dòng nằm trước câu lệnh mà nó áp dụng, và thụt lề với độ sâu giống như câu lệnh. Sử dụng khoảng trắng thích hợp để tránh mã lệnh khó đọc.

2. Các ghi chú trong-dòng-lệnh có thể sử dụng thường xuyên trong khi viết lệnh để lồng các ghi chú lập trình cho bạn. Ví dụ như, bạn có thể tạo định danh cho các đoạn chương trình đã hoàn tất, các đoạn còn cần phải làm nhiều hơn, các vị trí có khả năng gây lỗi, các điểm có thể cải tiến trong tương lai nảy ra trong đầu bạn, các khuyết điểm có thể có của giải thuật được cài đặt, v.v… Dĩ nhiên, hầu hết những ghi chú này sẽ được xóa bỏ khi chương trình hoàn tất.

Thông báo lỗi

Nằm trong tập tin nguồn, có dạng bảng:

ID Chuỗi thông báo

Tên tập tin

Assemblies: Class.c hoặc Class.cs (Ký tự đầu của tất cả các từ là in hoa).

Interface: frmName.cs (từ đầu chữ thường và tất cả các từ còn lại có ký tự đầu in hoa).

Các dòng lệnh trong hàm

Các hàm hiếm khi có quá 100 dòng lệnh. Trong trường hợp nó vượt quá 100 dòng, thì mục tiêu của hàm là không rỏ ràng. Hãy đọc lại và thử và tối ưu mã nguồn. Nếu không thể, hãy tìm cách tách thành nhiều hàm nhỏ hơn với các mục đích cụ thể hơn. Hãy nhờ sự giúp đỡ của các thành viên khác trong những trường hợp này.

Đừng sử dụng các số khó hiểu. Hãy sử dụng HẰNG mỗi khi có thể, ví dụ:

for(i=0; i<100; i++)

Nên viết lại là:

for(i=lowervalue; i<uppervalue; i++)

Điều này giúp cho câu lệnh dễ hiểu hơn nhiều.

Lưu ý:

Mỗi dòng lệnh phải vừa vặn trong 80 cột. Nếu không, hãy tách nó thành nhiều dòng.


Bài viết này được đóng góp bởi LongDT. Nếu bạn thích V1Study và muốn đóng góp, bạn gửi bài viết về địa chỉ [email protected] hoặc gửi vào Zalo 0986.589.410. Bài viết của bạn sẽ xuất hiện sau khi được duyệt và bạn có thể trợ giúp những người học khác.
« Prev
Next »
Copied !!!