Bagaimana merujuk ke area kode tertentu dalam dokumentasi?

9

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.

documentation comments loneboat
sumber
Apakah Anda merujuk ke lokasi spesifik dari metode terlampir atau dari komentar ringkasan file teratas? Dalam kasus terakhir, Anda dapat menggunakan gaya JavaDoc "#".
arin
Saya biasanya merujuk ke file dan metode ("Pemberitahuan dalam file ABC dalam metode XYZ begini-dan-begitu yang terjadi") tapi saya ingin tahu jawaban apa yang masuk.
Michael Itzoe
7
Bukankah lebih bijaksana dalam hal ini untuk hanya memasukkan komentar ke dalam kode aktual?
Robert Harvey
adakah seseorang dalam tim yang dapat meninjau dokumentasi Anda dan memberikan umpan balik?
nyamuk
Memiliki kebutuhan untuk ini, terdengar seperti ada efek samping dalam metode lain yang Anda gunakan secara eksplisit.
Michael Shaw

Jawaban:

1

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.

treecoder
sumber
Terima kasih untuk umpan baliknya! Saya berpikir "jelaskan konteksnya" terlihat seperti pilihan terbaik bagi saya. Terima kasih lagi.
loneboat
2
Memiliki masalah unik cukup sering berarti Anda melakukan sesuatu dengan cara yang salah.
Thijs van Dien
2
@ ThijsvanDien: Percayalah, kami melakukan banyak hal dengan cara yang salah di sini! ;-)
loneboat
3

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.

Laurent Bourgault-Roy
sumber
1
Jawaban ini harus menjadi pemenang, kecuali untuk poin awal OP bahwa dia meninggalkan proyek dan mungkin memiliki waktu terbatas dan mungkin juga tidak boleh memperkenalkan perubahan saat keluar. Tetapi benar-benar benar - jika ada sesuatu yang cukup kompleks untuk merujuk pada eksternal, letakkan di unit kode yang bernama sendiri.
Ross Patterson
2

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.

miraculixx
sumber