Mã tài liệu: Công khai so với không công khai?

Tôi là một trong những nhà phát triển có suy nghĩ rằng mã được viết nên tự giải thích và đọc như một cuốn sách.

TUY NHIÊN, khi phát triển mã thư viện cho người khác sử dụng, tôi cố gắng đưa càng nhiều tài liệu vào các tệp tiêu đề càng tốt; Điều này đưa ra câu hỏi: Các phương pháp tài liệu không công khai thậm chí có đáng thời gian không? Họ sẽ không được sử dụng chúng trực tiếp, trên thực tế, họ không thể. Đồng thời nếu tôi phân phối mã thô (mặc dù miễn cưỡng) những phương thức không công khai đó sẽ hiển thị và có thể cần giải thích.

Chỉ cần tìm kiếm một số tiêu chuẩn và thực hành mà tất cả các bạn nhìn thấy hoặc sử dụng trong chuyến đi của bạn.

Tôi sẽ không bao giờ xem xét bỏ qua tài liệu cho nội bộ chỉ vì "người dùng cuối" sẽ không sử dụng chúng; bảo trì mã là quá đủ lý do để bao gồm các nhận xét tài liệu cho tất cả các thành phần, trên thực tế, đặc biệt là đối với các phần bên trong có xu hướng phức tạp nhất (và thay đổi).

Điều đó nói rằng, có thể có một trường hợp hợp lệ được thực hiện để giữ cho chúng bị giới hạn ở mã nguồn không phải tiêu đề (chứ không phải là tài liệu công khai), để duy trì sự trừu tượng hóa.

Đây là tất cả khá chủ quan, tâm trí bạn.

Ok, tôi thêm cách bình luận / tài liệu của tôi vào hình ảnh cho đa dạng. Lý do là tôi tránh mô tả các hàm hoặc các hàm thành viên chỉ được khai báo ở đó trong tiêu đề. Một mặt tôi sợ phải thêm quá nhiều tiếng ồn vào tiêu đề. Mặt khác, tài liệu cùng với định nghĩa sẽ dễ dàng hơn cho người bảo trì khớp. Doxygen cũng không quan tâm theo cách nào và có thể lọc tư nhân ra nếu cần.

Trong tiêu đề lớp:

• bao gồm các tiêu đề (tại sao)
• định nghĩa lớp luôn (mục đích và trách nhiệm)
• Các chức năng ảo thuần túy luôn luôn (hợp đồng đầy đủ)
• các hàm nội tuyến trừ khi getters tự giải thích
• các loại khai báo khác trừ khi tự giải thích
• thành viên dữ liệu tĩnh (tại sao)
• thành viên dữ liệu khác trừ khi tự giải thích
• các macro nếu có (hợp đồng và tại sao)

Trong mã thực hiện lớp:

• khai báo cục bộ giống như trong tiêu đề
• định nghĩa hàm luôn (hợp đồng đầy đủ)
• định nghĩa hàm thành viên luôn luôn (hợp đồng đầy đủ hoặc tham chiếu đến gốc của ghi đè ảo)
• biến tĩnh được định nghĩa nếu có (mục đích tại sao)

Trong tiêu đề mẫu:

• đã sáp nhập ở trên và
• loại phù hợp / không phù hợp cho các đối số mẫu và
• mức độ phù hợp được phát hiện tĩnh

Ở private:đầu phần riêng là tất cả các tài liệu người dùng cần.

Tài liệu là bất kỳ ngày nào có giá trị, nó giúp giải thích các trường hợp sử dụng và câu chuyện một cách ngắn gọn. Bao nhiêu mã là tự giải thích nó không thể giải thích doanh nghiệp dễ dàng như vài dòng kể chuyện. Mã chắc chắn sẽ yêu cầu người dùng tuân theo logic ngoài việc hiểu những gì đang diễn ra. :-) 2 xu của tôi ...

Chắc chắn rồi!

Mã đó nên được tự ghi lại là một khẩu hiệu để sống. Tuy nhiên, tôi sẽ đi xa hơn để nói rằng mã riêng cần nhiều tài liệu, nếu không, nhiều hơn mã công khai, bởi vì ở đây thường có nhiều giả định nhất thường xảy ra, chỉ vì người viết mã giả định rằng nó sẽ vẫn ở trong bóng tối . Vì vậy, một vài tháng sau, khi một lỗi xảy ra theo cách của bạn, bạn sẽ dành thời gian cố gắng để nhớ ý tưởng đằng sau mã (có lẽ là chính bạn) đã viết.

Tài liệu không nên ở đó như một món quà tốt đẹp cho người khác. Tài liệu, trong tất cả các mặt của nó (tên biến được chọn tốt, tên lớp tự tạo tài liệu, mã được tổ chức tốt, phương thức được phân đoạn chính xác, v.v.) là một món quà cho tất cả những ai có thể tiếp xúc với mã của bạn, bao gồm cả bạn.