Bagaimana merujuk ke area kode tertentu dalam dokumentasi?

Saya akan meninggalkan proyek, dan sebelum saya pergi, bos saya telah meminta saya untuk mendokumentasikan kode (saya belum mendokumentasikan dengan baik). Ini bukan masalah besar, proyek ini tidak terlalu rumit. Tetapi saya menemukan tempat dalam dokumentasi saya di mana saya ingin mengatakan, "Perhatikan pada saluran XYZ bahwa ini-dan-itu terjadi."

Dalam hal ini, tidak masuk akal untuk merujuk ke nomor baris tertentu, karena menambah atau menghapus satu baris kode akan segera memutakhirkan dokumentasi. Apakah ada beberapa praktik terbaik untuk merujuk ke baris kode tertentu tanpa merujuknya dengan nomor baris?

Saya telah mempertimbangkan mengotori kode dengan komentar seperti:

/* linetag 38FECD4F */

Di mana "38FECD4F" adalah beberapa tag unik untuk baris tertentu. Lalu saya dapat memasukkan dokumentasi, "Pada baris yang ditandai '38FECD4F', perhatikan bahwa ini-dan-itu terjadi."

Ada ide lain? Saya merasa lebih baik mendokumentasikan unit kode secara keseluruhan, daripada bagian-bagian tertentu dari mereka, tetapi dalam kasus proyek khusus ini ada petak kode prosedur yang PANJANG, yang tidak pernah dire-refour menjadi unit yang lebih kecil.

Jika saya memahaminya dengan benar, Anda tampaknya memiliki masalah unik. Apa yang ingin Anda lakukan merujuk pada baris kode tertentu dalam komentar yang ditulis di bagian lain dari kode yang sama.

Saya biasanya tidak menemukan skenario seperti itu di mana saya perlu merujuk ke baris exect # dalam beberapa komentar yang ditulis di tempat lain - umumnya kode didokumentasikan tepat di tempat itu ditulis.

Saya tidak tahu cara standar untuk melakukan ini - tetapi dari atas kepala saya ...

Anda dapat merujuk ke bagian-bagian kode melalui konteksnya - yaitu hal-hal yang mengelilinginya.

Perhatikan di atas definisi func1 () bahwa ini-dan-itu terjadi

Perhatikan bahwa tepat setelah for loop yang berulang di recordXYZItr, kita juga memanggil metode gc ()

Perhatian: Dalam metode yahoo (), tepat setelah deklarasi variabel PQ, kita juga menukar nilai dalam A dan B, jadi objek mapABC di sana juga perlu disalin

Cara lain adalah dengan menambahkan tag deskriptif. Alih-alih sesuatu seperti 38FECD4F, Anda dapat mengatakan Some XYZ implementationatau BUGFIX 1474, dan kemudian merujuknya ke tempat lain.

Itu tergantung banyak bagaimana kode itu ditulis, dan saya mengerti bahwa itu dapat menyebabkan banyak refactoring yang tidak Anda lakukan di sini.

Tetapi ... jika Anda perlu merujuk ke baris kode tertentu sebagai satu kesatuan, bukankah itu berarti bahwa beberapa kode itu mewakili operasi abstrak, dan dengan demikian dapat direaktualisasikan dalam metode / fungsinya sendiri? Setelah itu dalam suatu metode, itu cukup mudah, cukup merujuk ke namespace.class.methodTentu saja itu berarti memiliki metode yang sangat kecil, sekitar 5-10 baris panjang atau bahkan kurang. Dengan Doxygen, Anda dapat menempatkan dokumentasi di atas metode, dan itu akan selalu tetap sinkron dengan nama metode / kelas / namespace.

Saya sarankan Anda mengambil pendekatan yang berbeda, selain menghubungkan dari beberapa dokumentasi kode-eksternal ke kode:

1. tambahkan komentar ke kode Anda, menggunakan alat seperti doxygen .

2. jika ada kebutuhan untuk menjelaskan beberapa konsep lebih terinci daripada yang cocok dalam dokumentasi kode (baru dibuat), Anda selalu dapat membuat dokumen terpisah dan tautan ke sana.

Dengan cara ini Anda dapat dengan mudah menghasilkan dokumentasi sebagai halaman web atau sebagai PDF, dan tetap konsisten dengan kode. Menggunakan beberapa tag buatan akan menjadi sangat sulit untuk dipertahankan dan bahkan lebih sulit untuk dipahami bagi yang belum tahu.