Tại sao /// khối bình luận quan trọng?

Ai đó đã từng nói rằng chúng ta nên thêm tiền tố vào tất cả các phương thức của mình bằng các /// <summary>khối nhận xét (C #) nhưng không giải thích lý do.

Tôi bắt đầu sử dụng chúng và thấy chúng làm phiền tôi khá nhiều, vì vậy đã ngừng sử dụng chúng ngoại trừ các thư viện và phương thức tĩnh. Chúng cồng kềnh và tôi luôn quên cập nhật chúng.

Có bất kỳ lý do tốt để sử dụng /// <summary>các khối nhận xét trong mã của bạn?

Tôi thường sử dụng các //bình luận mọi lúc, đó chỉ là các /// <summary>khối tôi đang tự hỏi.

Sử dụng chúng càng nhiều càng tốt.

Vâng, đó là những bình luận đặc biệt trở thành tài liệu cho phương pháp. Nội dung của <summary>, các thẻ tham số, v.v. được tạo sẽ hiển thị trong intellisense khi bạn hoặc người khác chuẩn bị gọi phương thức của bạn. Về cơ bản họ có thể xem tất cả các tài liệu cho phương thức hoặc lớp của bạn mà không cần phải tự đi đến tệp để tìm ra nó làm gì (hoặc cố gắng chỉ đọc chữ ký phương thức và hy vọng điều tốt nhất).

Có, hoàn toàn sử dụng chúng cho bất cứ điều gì bạn muốn giữ, hoặc có thể được chia sẻ.

Ngoài ra, sử dụng chúng cùng với Sand Castle và Trình tạo tệp trợ giúp của Sand Castle , lấy đầu ra XML và biến nó thành tài liệu đẹp, theo kiểu MSDN.

Nơi cuối cùng tôi làm việc, chúng tôi xây dựng lại tài liệu mỗi tối và lưu trữ nó như một trang chủ nội bộ. Tên viết tắt của công ty là MF, vì vậy nó là MFDN;)

Thông thường mặc dù tôi chỉ tạo một tệp .chm, dễ dàng chia sẻ xung quanh.

Bạn sẽ ngạc nhiên về việc bạn nghiện tài liệu như thế nào khi bạn bắt đầu nhìn thấy nó ở định dạng MSDN!

Nếu tiêu chuẩn mã hóa của bạn yêu cầu bạn sử dụng các nhận xét đó (và tiêu chuẩn mã hóa cho API hoặc khung có thể yêu cầu điều đó), thì bạn không có lựa chọn nào khác, bạn phải sử dụng các nhận xét đó.

Nếu không, hãy xem xét nghiêm túc không sử dụng ý kiến ​​như vậy. Bạn có thể tránh chúng trong hầu hết các trường hợp bằng cách thay đổi mã của bạn như thế này:

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

đến

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

đến

    public bool IsAuthorizedToAccessResource( User user ) {

    }

Lớp học, phương pháp và cách đặt tên thuộc tính của bạn phải rõ ràng, vì vậy nếu bạn cần những thứ này, nó có thể là một mùi.

Tuy nhiên, tôi khuyên bạn nên sử dụng chúng trên bất kỳ lớp, phương thức và thuộc tính công khai nào trong API, thư viện, v.v ... Ít nhất, họ sẽ tạo tài liệu để giúp bất kỳ nhà phát triển nào sử dụng nó và sẽ ngăn bạn khỏi để viết chúng.

Nhưng dù sao bạn cũng cắt nó, duy trì chúng hoặc xóa chúng.

Nếu bạn thấy rằng bạn phải tiếp tục quay lại và chỉnh sửa nhận xét của mình để tương ứng với mã mới, bạn có thể đã làm sai chúng ngay từ đầu. Phần tử tóm tắt phải chứa chính xác điều đó - một bản tóm tắt - những gì và lý do tại sao điều bạn đang tóm tắt.

Mô tả làm thế nào một cái gì đó hoạt động trong các ý kiến ​​vi phạm DRY. Nếu mã của bạn không đủ tự mô tả, có lẽ bạn nên quay lại và cấu trúc lại.

Vâng, tôi đã tạo ra chúng. [khi xây dựng hệ thống mới từ đầu]

Không, tôi chưa bao giờ được hưởng lợi từ họ. [khi làm việc trên các hệ thống hiện có cần bảo trì]

Tôi đã thấy rằng các nhận xét "Tóm tắt" cuối cùng có xu hướng không đồng bộ với mã. Và một khi tôi nhận thấy một vài bình luận có hành vi xấu, tôi có xu hướng mất niềm tin vào tất cả các bình luận về dự án đó - bạn không bao giờ chắc chắn nên tin vào ý kiến ​​nào.

Quên làm một cái gì đó không làm cho nó một ý tưởng tồi. Quên để cập nhật bất kỳ tài liệu là. Tôi đã tìm thấy những thứ này rất hữu ích trong lập trình của tôi và những người kế thừa mã của tôi rất biết ơn khi có chúng.

Đây là một trong những cách dễ thấy nhất để ghi lại mã của bạn.

Thật là khó khăn khi phải tìm mã nguồn để đọc tài liệu nội tuyến hoặc tìm kiếm một tài liệu đi qua những gì mã làm. Nếu bạn có thể có một cái gì đó hữu ích bật lên thông qua trí thông minh thì mọi người sẽ yêu bạn.

" Nó phải được sử dụng rất nhiều, như tôi;) "

Tôi đã từng chơi với các bình luận (///). Đối với một lớp học, bạn chỉ cần bình luận như thế này

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

Nhưng, đối với một phương thức, bạn có thể bổ sung thêm bằng cách đưa ra mô tả cho các tham số và kiểu trả về.

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

Bạn có thể sử dụng một lối tắt để tạo bình luận này (///+Tab).

sử dụng chúng ngoại trừ thư viện

Đó là thời gian chúng hữu ích. Với việc tạo Tài liệu XML được bật và tham chiếu đến tổ hợp, không có dự án của nó, sẽ hiển thị chi tiết hơn trong intellisense.

Nhưng đối với các bên trong của dự án hiện tại, họ chỉ cản trở.

Tôi sử dụng chúng, nhưng như một số người khác đã nói không phổ biến. Đối với các phương thức nhỏ, chúng có thể dễ dàng lớn hơn mã mà chúng đang giải thích. Chúng rất hữu ích để tạo tài liệu có thể được trao cho những người mới sử dụng hệ thống để họ có một cái gì đó để tham khảo trong khi tìm hiểu nó. Mặc dù, là các lập trình viên, chúng ta thường có thể tìm ra một số mã cho nó là tốt để có các ý kiến ​​để hướng dẫn chúng ta và hành động như một cái nạng. Nếu nó có phải được viết xuống một nơi nào đó trong mã là nơi nó có nhiều khả năng để luôn cập nhật (nhiều khả năng hơn một số tài liệu Word nổi xung quanh).

Tôi sử dụng tương đương trong VB (vì họ sẽ không cho tôi sử dụng C # - rõ ràng là quá khó ... không có nhận xét nào.) Tôi thấy chúng rất tiện lợi. Hầu hết thời gian tôi đợi cho đến khi thủ tục hoặc chức năng được hoàn thành khá nhiều trước khi đưa chúng vào, nếu chỉ để tránh phải thay đổi các nhận xét - hoặc khiến chúng "không đồng bộ".

Tôi không nhất thiết phải viết một cuốn tiểu thuyết - chỉ là những điều cơ bản, mô tả tham số và một số nhận xét (thường là khi có một cái gì đó "khác thường" đang diễn ra ở đó - cách giải quyết hoặc những thứ nhảm nhí khác mà tôi không có trong đó nhưng có không có lựa chọn "cho bây giờ".) (Vâng, tôi biết, rằng "cho bây giờ" có thể kéo dài nhiều năm.)

Tôi bị kích thích nghiêm trọng bởi mã không bị lỗi. Một chuyên gia tư vấn đã viết phiên bản ban đầu của một trong các thành phần của chúng tôi và không bình luận bất cứ điều gì và sự lựa chọn tên của anh ấy được mong muốn ở đây và ở đó. Anh ấy đã đi được hơn một năm và chúng tôi vẫn đang phân loại đồ đạc của anh ấy (ngoài việc làm việc với những thứ của chúng tôi.)