Nhận xét giao diện, triển khai hoặc cả hai?

Question

Tôi tưởng tượng rằng tất cả chúng ta (khi chúng ta có thể bị làm phiền!) Bình luận các giao diện của chúng ta. ví dụ.

/// <summary> 
/// Foo Interface 
/// </summary> 
public interface Foo 
{ 
    /// <summary> 
    /// Will 'bar' 
    /// </summary> 
    /// <param name="wibble">Wibble factor</param> 
    void Bar(string wibble); 
} 

Bạn cũng nhận xét việc triển khai (cũng có thể được cung cấp cho khách hàng, ví dụ như một phần của thư viện)? Nếu vậy, làm thế nào để bạn quản lý việc giữ hai đồng bộ? Hay bạn chỉ cần thêm nhận xét 'Xem giao diện cho tài liệu'?

Cảm ơn

Answer 1

Theo nguyên tắc chung, tôi sử dụng DRY cùng (Do not Repeat Yourself) nguyên tắc như với mã:

• trên giao diện, tài liệu giao diện
• tình hình thực hiện, ghi lại chi tiết cụ thể thực hiện

Java cụ thể: khi ghi lại việc thực hiện, sử dụng {} @inheritDoc thẻ để "bao gồm" javadocs f rom giao diện.

Để biết thêm thông tin:

• Official javadoc documentation
• Một số không chính thức advice.

Answer 2

Nếu bạn sử dụng GhostDoc addin, nó cập nhật việc thực hiện với những nhận xét từ giao diện khi bạn click chuột phải và chọn "Tài liệu này" trên phương pháp này.

Answer 3

Nhận xét giao diện phải đủ tài liệu để tìm hiểu cách sử dụng triển khai thực tế. Thời gian duy nhất tôi thêm ý kiến ​​vào việc thực hiện là nếu nó có các chức năng riêng được chèn vào để thỏa mãn giao diện, tuy nhiên chúng sẽ là các bình luận nội bộ và sẽ không được nhìn thấy trong tài liệu trực tuyến hoặc có sẵn cho khách hàng.

Triển khai chỉ là điều đó, miễn là chúng tuân theo giao diện, không cần phải ghi chúng riêng biệt.

Answer 4

Chỉ giao diện. Nhận xét cả hai đều là trùng lặp và có khả năng hai bộ nhận xét cuối cùng sẽ không đồng bộ nếu mã thay đổi. Bình luận việc thực hiện với "thực hiện MyInterface" ... Những điều như Doxygen sẽ tạo ra tài liệu bao gồm các tài liệu có nguồn gốc vào tài liệu cho việc thực hiện anyway (nếu bạn thiết lập chúng một cách chính xác).

Answer 5

Đối với C# nó phụ thuộc IMO: Nếu bạn sử dụng triển khai giao diện rõ ràng, thì tôi sẽ không ghi lại việc triển khai.

Tuy nhiên, nếu bạn triển khai giao diện trực tiếp và hiển thị các thành viên của giao diện với đối tượng của bạn thì các phương pháp này cũng phải được ghi lại.

Như Nath đã nói, bạn có thể sử dụng GhostDoc để tự động chèn tài liệu của giao diện vào triển khai. Tôi đã ánh xạ tài liệu Lệnh này tới phím tắt Ctrl + Shift + D và một trong các phím bấm mà tôi gần như tự động nhấn. Tôi tin rằng ReSharper cũng có tùy chọn để chèn tài liệu của giao diện, khi nó thực hiện các phương pháp cho bạn.

Answer 6

Chúng tôi chỉ bình luận về giao diện, các nhận xét rất dễ để không đồng bộ với giao diện hoặc lớp cơ sở/giao diện cơ bản, thật tuyệt khi có nó ở một nơi.

Mặc dù có vẻ như @Nath có thể đề xuất công cụ tài liệu tự động giúp giữ mọi thứ lại với nhau (âm thanh tuyệt vời nếu bạn sử dụng). Tại WhereIWorkAndYouDontCare các ý kiến ​​là dành cho dev do đó, một nơi duy nhất trong các mã được ưa thích

Answer 7

Tôi đã tạo một công cụ xử lý sau các tệp tài liệu XML để thêm hỗ trợ cho thẻ < inheritdoc/>.

Mặc dù nó không hỗ trợ Intellisense trong mã nguồn, nó cho phép các tệp tài liệu XML được sửa đổi được bao gồm trong gói NuGet và do đó làm việc với Intellisense trong các gói NuGet được tham chiếu.

Đó là tại www.inheritdoc.io (phiên bản miễn phí có sẵn).