แสดงความคิดเห็นอินเทอร์เฟซการใช้งานหรือทั้งสองอย่าง?

ฉันคิดว่าเราทุกคน (เมื่อเราสามารถใส่ใจ!) แสดงความคิดเห็นอินเทอร์เฟซของเรา เช่น

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

คุณยังแสดงความคิดเห็นการดำเนินการ (ซึ่งอาจมีให้กับลูกค้าเช่นเป็นส่วนหนึ่งของห้องสมุด aa)? ถ้าเป็นเช่นนั้นคุณจะจัดการทำให้ทั้งสองซิงค์กันได้อย่างไร หรือคุณเพียงแค่เพิ่มความคิดเห็น 'ดูอินเตอร์เฟซสำหรับเอกสารประกอบ'?

ขอบคุณ

ตามกฎทั่วไปฉันใช้หลักการ DRY (อย่าทำซ้ำตัวเอง) เช่นเดียวกับรหัส:

• บนอินเทอร์เฟซเอกสารอินเทอร์เฟซ
• ในการดำเนินการเอกสารการดำเนินงานเฉพาะ

Java เฉพาะ : เมื่อจัดทำเอกสารการนำไปใช้ให้ใช้แท็ก {@inheritDoc} เพื่อ "รวม" javadocs จากอินเตอร์เฟส

สำหรับข้อมูลเพิ่มเติม:

• เอกสาร javadoc อย่างเป็นทางการ
• บางอย่างไม่เป็นทางการคำแนะนำ

หากคุณใช้GhostDoc addin โปรแกรมจะอัปเดตการใช้งานด้วยความคิดเห็นจากอินเทอร์เฟซเมื่อคุณคลิกขวาและเลือก "เอกสารนี้" ในวิธีการ

สำหรับ C # ขึ้นอยู่กับ IMO: หากคุณใช้การใช้งานอินเทอร์เฟซที่ชัดเจนดังนั้นฉันจะไม่บันทึกการใช้งาน

อย่างไรก็ตามถ้าคุณใช้อินเทอร์เฟซโดยตรงและเปิดเผยสมาชิกของอินเทอร์เฟซกับวัตถุของคุณแล้ววิธีการเหล่านี้จะต้องได้รับการบันทึกไว้ด้วย

ดังที่ Nath กล่าวว่าคุณสามารถใช้ GhostDoc เพื่อแทรกเอกสารของอินเทอร์เฟซในการใช้งานโดยอัตโนมัติ ฉันทำการแมปเอกสารคำสั่งนี้กับทางลัด Ctrl + Shift + D และหนึ่งในการกดแป้นที่ฉันกดโดยอัตโนมัติ ฉันเชื่อว่า ReSharper ยังมีตัวเลือกในการแทรกเอกสารของอินเทอร์เฟซเมื่อใช้วิธีการสำหรับคุณ

อินเทอร์เฟซเท่านั้น การแสดงความคิดเห็นทั้งคู่เป็นการทำซ้ำและเป็นไปได้ว่าในที่สุดความคิดเห็นทั้งสองชุดจะหายไปในที่สุดหากรหัสเปลี่ยนแปลง แสดงความคิดเห็นการใช้งานด้วย "ดำเนินการ MyInterface" ... สิ่งต่าง ๆ เช่น Doxygen จะสร้างเอกสารที่รวมเอกสารที่ได้รับมาไว้ในเอกสารสำหรับการนำไปใช้งานต่อไป (ถ้าคุณตั้งค่าอย่างถูกต้อง)

เราเพียงแค่แสดงความคิดเห็นอินเทอร์เฟซความคิดเห็นนั้นง่ายมากที่จะซิงค์กับคลาสหรืออินเทอร์เฟซที่ได้รับมาหรือพื้นฐานที่ดีที่มีไว้ในที่เดียว

แม้ว่ามันจะดูเหมือน @Nath อาจจะแนะนำเครื่องมือเอกสารอัตโนมัติที่ช่วยให้สิ่งต่าง ๆ เข้าด้วยกัน (ฟังดูเจ๋งถ้าคุณใช้มัน) ที่นี่ที่ WhereIWorkAndYouDontCare ความคิดเห็นมีไว้สำหรับการพัฒนาดังนั้นจึงควรมีสถานที่เดียวในรหัส

การแสดงความคิดเห็นอินเทอร์เฟซควรเป็นเอกสารเพียงพอที่จะเข้าใจวิธีการใช้งานจริง เวลาเดียวที่ฉันจะเพิ่มความคิดเห็นในการใช้งานคือถ้ามันมีฟังก์ชั่นส่วนตัวที่ถูกแทรกเพื่อตอบสนองอินเทอร์เฟซ แต่พวกเขาจะเป็นความคิดเห็นภายในเท่านั้นและจะไม่เห็นในเอกสารออนไลน์หรือลูกค้า

การติดตั้งใช้งานเป็นสิ่งที่ตราบใดที่พวกมันสอดคล้องกับอินเตอร์เฟสก็ไม่จำเป็นต้องจัดทำเอกสารแยกต่างหาก

ฉันสร้างเครื่องมือที่ประมวลผลไฟล์เอกสาร XML เพื่อเพิ่มการสนับสนุนสำหรับแท็ก <inheritdoc />

แม้ว่าจะไม่ช่วย Intellisense ในซอร์สโค้ด แต่ก็อนุญาตให้รวมไฟล์เอกสาร XML ที่แก้ไขแล้วในแพ็คเกจ NuGet ดังนั้นจึงทำงานกับ Intellisense ในแพ็คเกจ NuGet ที่อ้างอิงได้

มันอยู่ที่ www.inheritdoc.io (รุ่นฟรีใช้ได้)

คุณสามารถแสดงความคิดเห็นได้อย่างแน่นอน แต่แล้วคุณมีปัญหาในการรักษาทั้งสอง (ดังกล่าวก่อนหน้า) อย่างไรก็ตามในวันนี้และอายุมีรหัสการบริโภคใด ๆ จริงๆจะไม่ได้ใช้ IoC / DI และไม่ได้ใช้อินเตอร์เฟซ? ให้นี้ถ้าคุณเพียงต้องการที่จะแสดงความคิดเห็นอย่างใดอย่างหนึ่งฉันขอแนะนำให้แสดงความคิดเห็นอินเทอร์เฟซ วิธีนี้ผู้บริโภครหัสของคุณจะได้รับคำแนะนำที่ดีจาก Intellisense

การใช้งาน C #:

อินเตอร์เฟสสามารถมีลักษณะดังนี้:

    /// <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();
    }
}

การใช้งานอาจมีลักษณะเช่นนี้:

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