Sử dụng thuộc tính cho tài liệu trong C#

Question

Trong MSDN Attributes Tutorial họ sử dụng Author là một ví dụ cho một thuộc tính:

[Author("Jane Programmer", Version = 2), IsTested()] 
class Order 
{ 
    // add stuff here ... 
} 

Điều này dường như đối với tôi là một ý tưởng tốt vì nó sẽ cho phép bạn sử dụng phản ánh đến các lớp học nhóm theo tác giả (ví dụ) - hiển thị hiệu quả siêu dữ liệu thường có trong tài liệu cho trình biên dịch, điều này có thể hữu ích. Ngay lập tức tôi nghĩ "aha tôi nên sử dụng thuộc tính cho tất cả các tài liệu khối inline của tôi!" - ví dụ .:

[Author("Me")] 
[Description("Add 1 to value")] 
[Param("value", "The original value to add 1 to")] 
public int AddOne(value) {return value + 1;} 

Tuy nhiên không ai trong oftheanswers tôi có thể tìm về tài liệu hướng dẫn và các thuộc tính dường như cho thấy phương pháp này. Tất cả đều sử dụng XML cho tài liệu nội tuyến.

Có bất kỳ thuộc tính tích hợp nào để hỗ trợ tài liệu nội tuyến không? Nếu không, có bất kỳ thư viện/gói nào ngoài đó bao gồm bộ thuộc tính được xác định trước cho tài liệu nội tuyến không?

Answer 1

Một số nhược điểm của việc giữ tài liệu trong thuộc tính:

• nghèo định dạng cho văn bản dài;
• không có hỗ trợ bởi tiện ích bổ sung Visual Studio (ví dụ: sử dụng tính năng xem trước tài liệu của ReSharper);
• không có công cụ tạo tài liệu của bên thứ ba hỗ trợ;
• bao gồm tài liệu trong các hội đồng giúp giảm đáng kể kỹ thuật đảo ngược;
• sao chép siêu dữ liệu trong mã nguồn có siêu dữ liệu được lưu trữ trong hệ thống kiểm soát phiên bản (không có điểm theo dõi bất kỳ tác giả và phiên bản nào trong mã nguồn, khi VCS cung cấp cho bạn nhiều thông tin chính xác hơn - VCS không nói dối).

Tôi không thể nghĩ ra bất kỳ lợi thế nào ngay bây giờ. Trong trường hợp tôi cần thực sự cần, nó luôn có thể phân tích cú pháp các nhận xét tài liệu XML và chuyển đổi toàn bộ codebase thành bất kỳ dạng được gán nào.

Answer 2

Câu hỏi ở đây có vẻ là 'tài liệu là gì?'. Nếu 'thứ' mà bạn quan tâm cần được truy cập bằng cách phản ánh thì giải pháp ngụ ý của bạn về các thuộc tính là một giải pháp. Nhưng nếu mục đích là sử dụng các công cụ tài liệu chuẩn để xây dựng tài liệu thì không phải như vậy.

Sự cần thiết ở đây đưa ra giải pháp. Sự cần thiết cho 'tài liệu' là gì. Có lẽ câu hỏi sai?

Answer 3

Chỉ cần đề cập đến nó vì lợi ích của sự hoàn chỉnh, trong các dự án kiểm tra bạn có thể làm:

[TestProperty(“Author”, “Ducky”)] 
public void SomeTest() 
{ 
     ... 
} 

Bạn có thể mở rộng cách tiếp cận đó cho mã thông thường. Tôi không thích nhận xét về các vấn đề lý thuyết. Điều đó nói rằng, có lẽ kịch bản sử dụng kho lưu trữ để trích xuất tất cả các "tác giả"/"biên tập" của tập tin/lớp/phương pháp cụ thể có thể được tạo ra.