Làm thế nào để tham khảo các lĩnh vực cụ thể của mã trong tài liệu?

Tôi sắp rời khỏi một dự án, và trước khi tôi đi, sếp của tôi đã yêu cầu tôi viết mã tài liệu (Tôi chưa làm tài liệu tốt lắm). Đó không phải là một vấn đề lớn, dự án không quá phức tạp. Nhưng tôi đang tìm địa điểm trong tài liệu của mình, nơi tôi muốn nói, "Lưu ý trên dòng XYZ rằng điều tương tự xảy ra."

Trong trường hợp này, không có nghĩa gì khi đề cập đến một số dòng cụ thể, vì việc thêm hoặc xóa một dòng mã sẽ ngay lập tức lỗi thời tài liệu. Có một số cách thực hành tốt nhất để tham chiếu đến một dòng mã cụ thể mà không đề cập đến nó theo số dòng?

Tôi đã xem xét việc xả rác mã với các ý kiến ​​như:

/* linetag 38FECD4F */

Trong đó "38FECD4F" là một số thẻ duy nhất cho dòng cụ thể đó. Sau đó, tôi có thể đưa vào tài liệu, "Trên dòng được gắn thẻ '38FECD4F', lưu ý rằng điều tương tự xảy ra."

Còn ý tưởng nào khác không? Tôi cảm thấy nói chung là tốt hơn để ghi lại toàn bộ các đơn vị mã, thay vì các phần cụ thể của chúng, nhưng trong trường hợp của dự án cụ thể này, có các chuỗi mã thủ tục dài, chưa bao giờ được tái cấu trúc thành các đơn vị nhỏ hơn.

Nếu tôi hiểu đúng, bạn dường như có một vấn đề duy nhất. Những gì bạn muốn làm nó đề cập đến một dòng mã cụ thể trong các bình luận được viết trong một số phần khác của cùng một mã.

Tôi thường không bắt gặp những tình huống như vậy khi tôi cần tham khảo một dòng ngoại lệ # trong một số nhận xét được viết ở nơi khác - nói chung mã được ghi lại ngay tại nơi nó được viết.

Tôi không biết bất kỳ cách tiêu chuẩn nào để làm điều này - nhưng ngoài đỉnh đầu của tôi ...

Bạn có thể tham khảo các phần của mã thông qua ngữ cảnh của nó - tức là những thứ xung quanh chúng.

Lưu ý ở trên định nghĩa của func1 () rằng điều tương tự xảy ra

Lưu ý rằng ngay sau vòng lặp for lặp lại trên recordXYZItr, chúng ta cũng đang gọi phương thức gc ()

Thận trọng: Trong phương thức yahoo (), ngay sau khi khai báo biến PQ, chúng tôi cũng hoán đổi các giá trị trong A và B, do đó, đối tượng mapABC cũng cần được sao chép

Một cách khác là thêm các thẻ mô tả. Thay vì một cái gì đó như 38FECD4F, bạn có thể nói Some XYZ implementationhoặc BUGFIX 1474, và sau đó đề cập đến điều đó ở một nơi khác.

Nó phụ thuộc rất nhiều vào cách mã được viết và tôi hiểu rằng nó có thể tạo ra một loạt các phép tái cấu trúc mà bạn không ở đây để làm.

Nhưng ... nếu bạn cần tham khảo một dòng mã cụ thể với tư cách là một đơn vị, thì điều đó có nghĩa là một số mã đại diện cho một hoạt động trừu tượng, và do đó có thể được tái cấu trúc theo phương thức / chức năng của chính nó? Khi đã ở trong một phương thức, nó khá dễ, chỉ cần tham khảo namespace.class.methodTất nhiên điều đó có nghĩa là có các phương thức rất nhỏ, dài khoảng 5-10 dòng hoặc thậm chí ít hơn. Với Doxygen, bạn có thể đặt tài liệu lên trên phương thức và nó sẽ luôn đồng bộ với tên của phương thức / lớp / không gian tên.

Tôi đề nghị bạn thực hiện một cách tiếp cận khác, ngoài việc liên kết từ một số tài liệu bên ngoài mã sang mã:

1. thêm ý kiến ​​vào mã của bạn, sử dụng một công cụ như doxygen .

2. nếu cần phải giải thích một số khái niệm chi tiết hơn là phù hợp trong tài liệu của mã (mới được tạo), bạn luôn có thể tạo một tài liệu riêng và liên kết đến đó.

Bằng cách này, bạn có thể dễ dàng tạo tài liệu dưới dạng trang web hoặc dưới dạng PDF và nó phù hợp với mã. Sử dụng một số thẻ nhân tạo sẽ trở nên rất khó để duy trì và thậm chí khó hiểu hơn đối với người không quen.