Nhận xét giao diện, thực hiện hay cả hai?

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!) Nhận xét các giao diện của chúng tôi. 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 thực hiện (cũng có thể được cung cấp cho khách hàng, ví dụ như là một phần của thư viện aa)? Nếu vậy làm thế nào để bạn quản lý giữ hai đồng bộ? Hay bạn chỉ cần thêm một bình luận 'Xem giao diện cho tài liệu'?

Cảm ơn

Theo nguyên tắc chung, tôi sử dụng cùng một nguyên tắc DRY (Đừng lặp lại chính mình) như với mã:

• trên giao diện, ghi lại giao diện
• về thực hiện, tài liệu cụ thể thực hiện

Java cụ thể : khi ghi lại quá trình triển khai, sử dụng thẻ {@inheritDoc} để "bao gồm" javadocs từ giao diện.

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

• Tài liệu javadoc chính thức
• Một số lời khuyên không chính thức .

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

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

Tuy nhiên, nếu bạn thực hiện giao diện trực tiếp và phơi bày 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 thức 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 quá trình thực hiện. 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 những tổ hợp phí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 thức cho bạn.

Giao diện thôi. Nhận xét cả hai là trùng lặp và có khả năng hai bộ bình luận cuối cùng sẽ không đồng bộ nếu mã thay đổi. Nhận xét việc triển khai với "triển khai MyInterface" ... Những thứ như Doxygen sẽ tạo ra các tài liệu bao gồm các tài liệu dẫn xuất vào tài liệu để thực hiện bằng mọi cách (nếu bạn thiết lập chúng chính xác).

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

Mặc dù có vẻ như @Nath có thể đề xuất một công cụ tài liệu tự động giúp giữ mọi thứ lại với nhau (nghe có vẻ hay nếu bạn sử dụng nó). Ở đây tại WhereIWorkAndYouDontCare, các bình luận dành cho nhà phát triển nên một vị trí duy nhất trong mã được ưu tiên

Nhận xét giao diện phải đủ tài liệu để tìm ra cách sử dụng thực hiện thực tế. Lần duy nhất tôi sẽ thêm ý kiến ​​vào việc triển khai là nếu nó có các chức năng riêng tư được chèn để đáp ứng giao diện, tuy nhiên chúng sẽ chỉ 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.

Việc triển khai chỉ là như vậy, miễn là chúng phù hợp với giao diện, không cần phải ghi lại chúng một cách riêng biệt.

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

Mặc dù nó không giúp với Intellisense trong mã nguồn, nhưng 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 đó hoạt động 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).

Bạn chắc chắn có thể nhận xét cả hai nhưng sau đó bạn có vấn đề duy trì cả hai (như đã đề cập trước đó). Tuy nhiên, trong thời đại ngày nay, có bất kỳ mã tiêu thụ nào thực sự sẽ không được sử dụng IoC / DI và không sử dụng giao diện? Đưa ra điều này nếu bạn chỉ muốn bình luận một cái tôi sẽ đề nghị bình luận giao diện. Bằng cách này, người tiêu dùng mã của bạn sẽ có nhiều khả năng nhận được các gợi ý intellisense tốt đẹp.

Cách sử dụng C #:

Giao diện có thể trông như thế này:

    /// <summary>
    /// Helper class to access various properties for the current site.
    /// </summary>
    public interface ISiteHelper
    {
        /// <summary>
        /// Gets the site id of the current site
        /// </summary>
        /// <returns>The site id.</returns>
        int GetSiteID();
    }
}

Việc thực hiện có thể như thế này:

/// <inheritdoc />
public class SiteHelper: ISiteHelper
{
    /// <inheritdoc />
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}