Cách tốt nhất để thêm tài liệu dành cho nhà phát triển vào các dự án Visual Studio của bạn

Question

Về cơ bản, câu hỏi là: Ở đâu (và ở định dạng nào), tôi nên lưu trữ tài liệu nhà phát triển văn bản được liên kết với các dự án Visual Studio của mình?

Để xây dựng: các nhận xét XML rất tuyệt, nhưng chúng không bao gồm tất cả các trường hợp sử dụng. Đôi khi, bạn muốn mô tả kiến ​​trúc lớp của dự án ở mức cao, thêm ghi chú sử dụng vào thư viện của bạn hoặc chỉ để lại bất kỳ loại thông điệp nào khác cho các nhà phát triển tương lai làm việc trong dự án này.

Tôi muốn thêm các tài liệu này trực tiếp dưới dạng tệp vào dự án Visual Studio, để đảm bảo (a) chúng sẵn có cho nhà phát triển mà không cần tìm kiếm thêm và (b) chúng được kiểm soát phiên bản (sử dụng cùng một svn/git/bất kỳ kho lưu trữ nào dưới dạng mã nguồn).

Hiện tại, tôi thêm một thư mục _Documentation vào dự án và sử dụng tệp văn bản, nhưng tôi không chắc đây có phải là giải pháp tốt nhất hay không. Visual Studio không có tùy chọn cho văn bản tự động gói từ và sửa lỗi ngắt dòng theo cách thủ công sau mỗi thay đổi gây phiền nhiễu. Mặt khác, các tài liệu Word không hoạt động tốt với điều khiển phiên bản, và TeX là quá nhiều rắc rối để thiết lập và dạy trên mỗi máy tính của nhà phát triển.

Có phương pháp hay nhất được thiết lập cho điều này không?

---

Tôi biết rằng có Edit/Advanced/word-wrap, nhưng điều này chỉ ảnh hưởng đến màn hình hiển thị, không phải là tập tin đó.

Answer 1

Tôi vừa gặp sự cố tương tự - chỉ tôi mới nhận thấy rằng tôi có thể thêm tệp HTML. Sau khi mở, chỉ cần chuyển sang "Thiết kế" ở cuối màn hình. Bạn có thể muốn thay đổi Build Action từ 'Nội dung' thành 'Không'

Vì nó là một tài liệu HTML mã hóa cứng, nó cũng có thể sử dụng hình ảnh inline (ví dụ như một sơ đồ)

Cũng Tôi đã chọn tạo một dự án riêng biệt (_Documentation) dưới dạng Biểu mẫu Windows, vì điều này sẽ cho phép tôi (hoặc một lập trình viên mới) có một ví dụ đang chạy.

Answer 2

tôi sử dụng GhostDoc (visual studio add-on) cho tài liệu của dự án của tôi như tôi thêm các lớp, phương pháp, tài sản vv: http://visualstudiogallery.msdn.microsoft.com/46A20578-F0D5-4B1E-B55D-F001A6345748

Answer 3

Bạn có tùy chọn, trong ý kiến ​​XML, bao gồm rất nhiều dữ liệu mà sau đó bạn có thể chọn một công cụ như Sandcastle (site) và biến thành một trang web tham khảo kiểu MSDN thực tế.

Tôi có xu hướng sử dụng phương pháp này và chỉ viết các nhận xét XML dài (MSDN comment tags) (nếu thích hợp) bằng cách sử dụng <para></para> để tạo đoạn văn và giải thích mọi mẫu, lý do kinh doanh hoặc thông tin kiến ​​trúc cần thiết cho các nhà phát triển/sửa đổi trong tương lai. Tôi cũng sử dụng nó để đưa ra các ví dụ sử dụng.

Một đợt kiểm tra tốt (được viết và đặt tên) cũng có thể thực sự chiếu sáng mục đích của mã, hoạt động như một thông số kỹ thuật.

Tôi hy vọng rằng có thể là một thông tin rất ít trong nghiên cứu của bạn :)

Answer 4

XML Bình luận tốt nhất là cung cấp tư liệu phương pháp đặc biệt và không lý tưởng cho các văn bản nội dung khái niệm dài. Các nhận xét XML dài có thể ảnh hưởng xấu đến khả năng đọc mã.

Tôi thích tính năng tài liệu khái niệm chủ đề của Sandcastle, chúng tôi có thể tạo và lưu trữ tài liệu khái niệm cho dù chức năng hoặc kiến ​​trúc có liên quan và hợp nhất nó với tài liệu mã (XML Comments). Đánh dấu mà bạn có thể sử dụng bằng văn bản các chủ đề khái niệm được mở rộng có nghĩa là chúng tôi thậm chí có thể tuân thủ các mẫu Enterprise.