Apakah boleh menempatkan tautan ke situs T&J dalam komentar program?

16

Dalam beberapa basis kode Anda dapat melihat komentar yang menyatakan hal-hal seperti:

 // Workaround for defect 'xxx', (See bug 1434594 on Sun's bugparade)

Jadi saya punya beberapa pertanyaan, tetapi semuanya terkait.

Apakah boleh menempatkan tautan ke pertanyaan SO dalam komentar program:

 // We're now mapping from the "sorted-on column" to original indices.
 //
 // There's apparently no easy way to do this in Java, so we're
 // re-inventing a wheel.
 //
 // (see why here, in SO question: http://stackoverflow.com/questions/951848)

Apakah anda melakukannya?

Dan apa kelemahannya? (lihat komentar pertama saya untuk kekurangan yang mengerikan)

comments Tristan St.
sumber
9
berkomentar pada diri sendiri: salah satu yang sangat tentang kelemahan ketika melakukan itu adalah bahwa karena fakta bahwa SO adalah Wiki ada persis nol jaminan bahwa jawaban (s) Anda mengandalkan masih akan benar (atau bahkan masih berada di sana). Heck, dalam beberapa kasus pertanyaan itu sendiri dapat ditutup atau diubah dari arti aslinya. Perbedaan besar antara "Lihat bug 1434594" pada parade bug Sun adalah Anda dijamin bahwa teks dari tautan bug Sun tidak akan ( "tidak akan" seperti yang didefinisikan oleh RFC2119) berubah. Ini sangat besar: fakta bahwa SO adalah wiki membuat saya gugup menempatkan tautan SO dalam komentar.
Tristan St.
7
Taruhan terbaik Anda adalah dengan meletakkan ringkasan jawaban SO yang jelas dan ringkas, lalu letakkan tautan referensi di bawahnya. Saya sudah melakukan itu pada beberapa kesempatan. Dengan begitu, jika SO pernah ada di bawah atau jawabannya dihapus / diedit, informasi inti yang Anda inginkan masih dalam ringkasan Anda. Sekarang, tergantung pada kompleksitas jawabannya, menulis ringkasan bisa menjadi tugas yang terpisah. Jika SO jawab tautan ke sesuatu yang lain, mungkin layak untuk tautan ke yang ke (terutama jika mereka kurang singkat daripada jawaban SO).
FrustratedWithFormsDesigner
5
@ Robert S .: tidak, ini bukan meta. Ini bukan tentang SO: Saya menerima SO apa adanya. Ini secara khusus tentang bagaimana menangani sumber daya mirip-SO dari komentar.
Tristan St.
1
Apakah Anda berbicara tentang kode yang Anda tulis untuk tim Anda? Tanya mereka.
1
Anda selalu dapat menyimpan seluruh halaman web sebagai halaman web lengkap, zip dan taruh di folder dokumenter Anda.

Jawaban:

7

Saya sudah melakukannya, mungkin tidak secara khusus untuk Stack Overflow, tetapi untuk blog teknis, forum, Usenet, Grup Google, atau tempat lain di mana "mengapa saya melakukan ini" mungkin tidak sepenuhnya jelas dari konteksnya.

Saya tidak melihat mengapa menggunakan SO seperti ini akan menjadi hal yang buruk, kecuali mereka mengarsipkan dan menghapus pertanyaan lama (yang menurut saya tidak, tetapi saya tidak yakin) - tetapi bahkan jika mereka melakukannya, tidak ada lebih buruk daripada situs lainnya.

Jika Anda benar-benar khawatir tentang hal itu, Anda selalu dapat mengambil tangkapan layar atau mengunduh halaman-halaman ini sebagai teks (atau mengalami kesulitan mendapatkan gambar, lembar gaya, dll.), Dan menyimpannya ke repositori pengetahuan di perusahaan Anda, melampirkan pengidentifikasi unik untuk itu, dan menempatkan pengenal unik itu di komentar Anda untuk memungkinkan Anda untuk referensi nanti - maka Anda akan memiliki tempat yang konsisten untuk hal semacam ini. Tapi itu mungkin berlebihan, tergantung pada kompleksitas dan pentingnya kode Anda.

Joe Enos
sumber
5

Secara umum, cara terbaik untuk membuat tautan ini adalah melalui sistem versi dan / atau sistem pelacakan bug. Persyaratan agar ini berfungsi adalah Anda dapat menautkan kode secara akurat ke pelacak kutu atau tempat di sistem versi tempat Anda memberikan komentar.


sumber
itu menarik: jadi Anda benar-benar menyarankan bahwa dalam kasus jawaban SO saya bisa mengambil HTML dan menyimpannya dalam DVCS saya (Mercurial tapi bukan itu intinya)?
Tristan St.
Nah, biasanya Anda tidak perlu semuanya, hanya bit yang relevan bukan? Dan Anda dapat referensi sumbernya.
5

Idealnya kode Anda tidak memerlukan komentar seperti itu karena terstruktur dengan baik, dll. Tapi ya, ketika situasi Anda kurang dari ideal, dapat diterima untuk memasukkan komentar seperti ini. Dan tautan ke stackoverflow.com sama baiknya (dan seringkali lebih baik!) Daripada yang lain.

Mudah-mudahan itu adalah komentar sementara, dan Anda akan diizinkan untuk kembali dan meningkatkan kode dan mengeluarkan komentar ini .

Saya belum memasukkan tautan StackOverflow.com dalam kode saya. Saya mencoba menghindari memasukkan tautan ke dalam kode, karena ini bau, tetapi ketika saatnya tiba saya tidak akan ragu.

Sunting : Saya pikir jawaban saya di atas memberi kesan bahwa kebutuhan akan komentar seperti ini dapat dihindari. Tentu saja terkadang itu tidak bisa dihindari; itu adalah bug di perpustakaan atau desain API yang buruk yang tidak dapat Anda kendalikan. Komentar seperti ini, termasuk tautan, sangat membantu pengembang berikutnya.

Patrick Karcher
sumber
2
hey, lihat yang satu itu, saya berharap akan ada sebuah "bersih" cara untuk berurusan dengan itu, tapi sangat sering itu tidak terjadi stackoverflow.com/questions/951848 Maksudku, bug dan inkonsistensi / API aneh, perilaku tak tercatat, dll adalah bagian dari kehidupan programmer kami :)
Tristan St.
2

Saya melihatnya seperti menulis makalah penelitian. Jika saya menggunakan ide orang lain, maka saya harus memberikan penghargaan untuk ide-ide itu. Saya telah menggunakan jawaban dari stackoverflow dalam kode saya sebelumnya, dan saya menambahkan tautan ke komentar metode.

Seperti yang disebutkan seseorang, SO adalah gaya wiki, jadi mungkin saja itu bisa berubah, tetapi umumnya idenya tetap sama.

Anda harus tetap memberikan penghargaan kepada orang lain ketika Anda menggunakan ide-idenya.

jmq
sumber
1

Jika Anda perlu menerapkan solusi, dan tidak jelas mengapa implementasi dilakukan dengan cara tertentu, maka komentar harus dibiarkan mengidentifikasi alasannya. Saya pikir menempatkan tautan ke referensi online baik-baik saja, tetapi Anda benar-benar harus membuat komentar Anda singkat, namun cukup lengkap bahwa tautan tersebut hanya akan memberikan penjelasan yang diperluas jika pembaca merasa perlu memeriksa ulang alasan Anda.

Jika di sisi lain kodenya telah disalin secara verbatim, maka tautan ke sumber asli hanya adil, dan mungkin diperlukan tergantung pada kata-kata dari lisensi di mana Anda telah diizinkan untuk menyalin karya penulis asli.

S.Robins
sumber