Tôi nên bao gồm những gì trong tiêu đề tài liệu lớp học của tôi

Tôi đang tìm định dạng tài liệu lớp thông tin cho các lớp Thực thể, Logic nghiệp vụ và Truy cập dữ liệu của tôi.

Tôi tìm thấy sau hai định dạng từ đây

Định dạng 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

Định dạng 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

Tôi cảm thấy sau đây là những yếu tố cơ bản

• Tác giả
• ngày tạo ra
• Sự miêu tả
• Lịch sử sửa đổi

vì tên không gian và tên lớp sẽ vẫn ở đó.

Xin vui lòng cho tôi biết suy nghĩ của bạn, định dạng nào được khuyến nghị và liệu có một cách viết lịch sử sửa đổi tiêu chuẩn?

Hầu hết các thông tin bạn đề xuất sẽ được tìm thấy trong kho lưu trữ nguồn.

Điều duy nhất bạn thực sự cần là phần mục đích, trong đó nói rằng lớp học ở đó để làm gì.

Sẽ thật tẻ nhạt khi nhìn vào kho lưu trữ mỗi khi bạn muốn biết các thông tin khác? Tôi sẽ nói không. Bạn có thường xuyên quan tâm ai là tác giả gốc? Hoặc khi tập tin được tạo lần đầu tiên? Các plugin (như Ankh SVN cho Visual Studio) thường cho phép bạn nhấp chuột phải vào tệp hiện tại của bạn và xem nhật ký kho lưu trữ cho tệp, vì vậy sẽ không quá rắc rối khi thực sự thấy thông tin này.

Ngoài ra, nếu bạn lưu trữ lịch sử phiên bản trong một bình luận, bình luận này cần được duy trì. Vì vậy, theo thời gian có một cơ hội nó có thể nói dối bạn. Kho lưu trữ mã nguồn tự động giữ dữ liệu lịch sử này, do đó không cần bảo trì đó và sẽ chính xác.

Có lớp mô tả, phương thức và tên biến . Điều này sẽ loại bỏ sự cần thiết cho các ý kiến ​​như mục đích và mô tả. Đôi khi chúng tôi nghĩ rằng tên phương thức càng ngắn càng tốt. Ngược lại, tạo một tên phương thức miễn là bạn muốn miễn là nó mô tả rõ ràng mục đích của nó. Chỉ có ghi chú là hoàn toàn quan trọng và giúp hiểu mã theo một số cách cụ thể. Khi thực hiện thay đổi mã, lập trình viên thường quên cập nhật ý kiến. Bạn có thể kết thúc với các bình luận và mã không đồng bộ và gây hại nhiều hơn là tốt.

Đọc bài viết này của Jeff Atwood - Mã hóa mà không cần bình luận .

Tôi sử dụng các thẻ tiêu chuẩn để tạo tài liệu. Không hơn không kém. Xem tại đây

Tôi không bao giờ đưa thông tin không thuộc về lớp. Tác giả, dữ liệu, bản sửa đổi là dữ liệu để lưu trữ trên Hệ thống kiểm soát phiên bản.

Hai định dạng được trình bày là vô dụng để tạo tài liệu và có lỗi lớn nhất về nhận xét, chúng liệt kê lịch sử sửa đổi.

Phần lớn thông tin này có thể được thêm vào bởi kho lưu trữ kiểm soát nguồn của bạn, khiến bạn thực sự chỉ có mô tả, mô tả chính xác phạm vi và hành vi của lớp. Tôi khuyên bạn nên xem một số Javadoc cho JDK Java làm ví dụ.

Tất cả mọi thứ trong danh sách đó là không cần thiết. Kiểm soát nguồn của bạn sẽ xử lý gần như tất cả mọi thứ và những gì nó không bao gồm được thực hiện bằng các quy ước đặt tên tốt.

Nếu tôi phải đọc "Mô tả" của bạn để tìm hiểu xem lớp của bạn đang làm gì thì (a) bạn đặt tên kém hoặc (b) bạn đã viết một lớp xấu đang làm quá nhiều (SRP).

Tôi đã chơi xung quanh với việc thay đổi các mẫu tiêu đề của mình, như những người khác chỉ ra, rất nhiều thông tin này có thể được tìm thấy trong kho lưu trữ và cho đến nay các lĩnh vực lớn mà tôi đang tìm cách lưu giữ như sau:

• Mô tả - Những gì đang được thực hiện bởi mã.
• Ghi chú - Bất cứ điều gì cần biết về mã không dễ dàng bắt nguồn từ các nhận xét trong chính mã.
• Tài liệu tham khảo - Bất kỳ tài liệu tham khảo nào mà mã phụ thuộc vào đó không được làm rõ mặc dù việc sử dụng includehoặc các câu lệnh tương tự.

Một mục cũng có thể hữu ích để bao gồm là một phần trên Từ khóa Trong khi bạn có thể thực hiện tìm kiếm tên hàm, lớp, struct, v.v., có thể có một số từ khóa mà các tên khác trong tệp không làm rõ. Hoặc đối với mã cũ, tài liệu kém, nó có thể là bước đầu tiên trong tài liệu mã để bảo trì.

Hầu hết các câu trả lời khác tôi đọc cho đến nay đều cho rằng chỉ có một kho lưu trữ luôn có sẵn

Vì sourcecode có thể mất kết nối đến kho lưu trữ (tức là nếu được sao chép), tài liệu lớp của tôi sẽ như sau:

• class documentation header (= khối nhận xét ở đầu tệp) chỉ chứa thông tin pháp lý bắt buộc (nghĩa là bản quyền của xyz theo giấy phép gpl)
• mọi thứ mà nhà phát triển sử dụng lớp nên biết nên đi vào lớp-java-doc-bình luận (hoặc tương đương .net của nó) để các ide-s hiện đại có thể hiển thị thông tin này dưới dạng thông tin công cụ sử dụng lớp mã nguồn.

Bạn cũng có thể thêm số vé cho lỗi hoặc yêu cầu tính năng để bạn có thể có một số manh mối trong đó / khi / tại sao lớp được tạo (nếu bạn may mắn đủ để bạn vẫn có thể truy cập vé sau một vài năm).

Khi nuôi ong yêu cầu sửa chữa các vấn đề trong các chương trình kế thừa nguồn đóng cũ, số vé ở đó khá có giá trị để tôi hiểu các yêu cầu ban đầu của mã.