Bagaimana cara menangani tautologi dalam komentar? [Tutup]

Kadang-kadang saya menemukan diri saya dalam situasi ketika bagian dari kode yang saya tulis adalah (atau tampaknya ) sangat jelas sehingga namanya pada dasarnya akan diulang sebagai komentar:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

(Contoh C #, tetapi silakan merujuk pertanyaan sebagai bahasa-agnostik).

Komentar seperti itu tidak berguna; apa yang saya lakukan salah? Apakah itu pilihan nama yang salah? Bagaimana saya bisa berkomentar bagian seperti ini lebih baik? Haruskah saya melewatkan komentar untuk hal-hal seperti ini?

Dalam sebagian besar proyek yang saya kerjakan, tidak ada banyak waktu untuk menulis komentar terperinci pada setiap anggota kelas.

Itu tidak berarti tidak ada waktu untuk komentar; sebaliknya, ada banyak waktu untuk komentar tautologis yang mendorong versi ulang dari apa pun yang sedang dikomentari. Mereka bekerja dengan baik sebagai titik awal .

Terutama mengingat penggunaan komentar Visual Studio yang menyertai IntelliSense , itu ide yang baik untuk memulai dengan sedikit informasi tentang bidang ini:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Dan saat Anda melanjutkan ke kode, ketika Anda tidak dapat mengingat apakah UpdateLocationlokasi pembaruan itu terjadi, atau lokasi di mana pembaruan itu dikirim, Anda harus meninjau kembali kode tersebut. Pada titik inilah Anda harus menambahkan informasi tambahan itu:

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Jika ada programmer lain yang menanyakan tentang detail pada sebuah bidang, perbarui komentar dengan informasi itu:

Pembaruan apa yang Example.UpdateLocationharus digunakan untuk menyimpan?

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Sama seperti sebuah program yang memiliki bug, komentar yang baik memiliki bug yang perlu diulangi. Tujuan dari komentar adalah untuk membantu dalam memahami kode ketika Anda mengunjungi kembali enam bulan kemudian dan tidak dapat mengingat apa pun tentang cara kerja program.

Dan seperti halnya pemrograman, komentar Anda harus dimulai di suatu tempat. Komentar tautologis adalah Hello World!komentar, ketika Anda berlatih menulis dan memperbarui dokumentasi, dokumentasi awal Anda akan menjadi lebih dan lebih tangguh.

Komentar tidak boleh menggandakan kode Anda. Komentar seharusnya tidak menjawab pertanyaan " bagaimana? ", Tetapi hanya " mengapa? " Dan " apa? ". Mengapa algoritma seperti itu dipilih, apa asumsi implisit di sini (kecuali bahasa Anda cukup kuat untuk mengekspresikannya dengan sistem tipe, kontrak, dan sejenisnya), apa alasan untuk melakukan hal ini sama sekali, dll.

Saya akan merekomendasikan untuk melihat praktik Pemrograman Literate untuk inspirasi.

Komentar harus menjelaskan kode, bukan menduplikatnya. Komentar tajuk ini hanya duplikat. Biarkan saja.

Tinggalkan mereka!

Biasanya, itu adalah praktik yang baik untuk menghapus komentar di mana informasi yang diungkapkan di dalamnya sudah ada di tempat lain. Jika Anda dapat mengekspresikan tujuan metode dengan jelas dan jelas dengan memberikan nama yang baik maka tidak perlu komentar .

Masukkan mereka!

Contoh Anda mengilustrasikan dua pengecualian untuk aturan ini:

Pertama, "UpdateLocation" mungkin (tergantung pada konteks) tidak jelas. Dalam hal ini, Anda harus memberikan nama yang lebih baik atau memberikan komentar untuk menghapus ambiguitas. Meningkatkan nama umumnya merupakan pilihan yang lebih baik, tetapi ini tidak selalu mungkin (ketika Anda menerapkan API yang diterbitkan, misalnya).

Kedua, "///" dalam C # menunjukkan komentar yang dimaksudkan untuk digunakan untuk menghasilkan dokumentasi secara otomatis. IDE menggunakan komentar ini untuk tips alat, dan ada alat (Sandcastle) yang dapat menghasilkan file bantuan dan sebagainya dari komentar ini. Dengan demikian, ada argumen untuk menyisipkan komentar ini bahkan jika metode yang mereka dokumentasikan sudah memiliki nama deskriptif. Namun, bahkan kemudian, banyak pengembang yang berpengalaman akan menyukai duplikasi informasi. Faktor penentu haruslah kebutuhan orang-orang yang menjadi tujuan dokumentasi.

Saya sangat tidak setuju dengan respons "jangan tulis komentar". Mengapa? Izinkan saya menunjukkan dengan sedikit mengubah contoh Anda.

public Uri UpdateLocation ();

Jadi apa fungsi fungsi ini:

• Apakah ini mengembalikan "perbarui lokasi"? atau
• Apakah itu "memperbarui" lokasi dan mengembalikan lokasi baru?

Anda dapat melihat bahwa tanpa komentar ada ambiguitas. Seorang pendatang baru dapat dengan mudah membuat kesalahan.

Dalam contoh Anda, ini adalah properti sehingga metode "get / set" mengungkapkan bahwa opsi kedua tidak benar dan itu memang berarti "perbarui lokasi" dan bukan "perbarui lokasi". Tetapi terlalu mudah untuk membuat kesalahan ini, terutama dalam kasus kata-kata yang tidak jelas seperti "pembaruan". Bermain aman. Jangan membingungkan seseorang yang baru dalam hal ini hanya karena menghemat beberapa detik dari waktu Anda.

/// <summary>blok digunakan untuk menghasilkan dokumentasi untuk IntelliSense dan dokumentasi API .

Jadi, jika ini adalah API yang dihadapi publik, Anda harus selalu menyertakan setidaknya <summary>komentar, bahkan jika tujuan dari fungsi tersebut harus jelas bagi pembaca.

Namun, ini pengecualian untuk aturan tersebut; secara umum, ingatlah untuk KERING (Jangan Ulangi Diri Sendiri) .

Isi komentar seperti itu hanya jika Anda tahu bagaimana Anda akan mendapat manfaat dari hal-hal seperti itu; kalau tidak, cukup usap mereka.

_{Bagi saya, kasus manfaat yang jelas adalah ketika ada pemeriksaan otomatis untuk komentar yang hilang dan saya menggunakan cek itu untuk mendeteksi kode di mana informasi penting perlu diisi; untuk ini saya memang mengisi beberapa tempat penampung - hanya untuk memastikan bahwa laporan alat tidak mengandung "alarm palsu".}

Saya pikir selalu ada cara untuk menghindari duplikasi terang-terangan . Selama bertahun-tahun saya menggunakan pasangan "templat pengisi" untuk kasus-kasus seperti milik Anda - kebanyakan seperti nama deskriptif-sendiri dan lihat di atas .

Untuk contoh khusus ini, saya akan menggunakan sesuatu yang "jenis deskriptif diri" (dengan asumsi itu bukan kasus di mana memusnahkan akan melakukan pekerjaan), seperti itu:

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

_{Contoh ketika saya bisa menggunakan lihat pengisi jenis di atas akan menjadi komentar Javadoc yang membutuhkan bidang khusus untuk nilai balik, parameter dan pengecualian. Cukup sering, saya menemukan bahwa lebih baik menjelaskan sebagian besar atau bahkan semua ini dalam kalimat ringkasan tunggal, metode yang mengembalikan <uraikan apa yang dikembalikan> untuk parameter yang disediakan <uraikan parameter> . Dalam kasus seperti itu, saya mengisi bidang yang diperlukan secara formal dengan tampilan polos di atas , mengarahkan pembaca ke deskripsi ringkasan.}

Inilah pertanyaan yang ingin saya tanyakan pada diri sendiri ketika memikirkan apakah akan menambahkan komentar ke dalam bagian kode: Apa yang dapat saya sampaikan yang akan membantu orang berikutnya memahami maksud keseluruhan kode dengan lebih baik, sehingga mereka dapat memperbarui, memperbaiki, atau memperpanjangnya lebih cepat dan lebih andal?

Kadang-kadang jawaban yang benar untuk pertanyaan ini adalah bahwa tidak ada banyak yang dapat Anda tambahkan pada saat itu dalam kode, karena Anda sudah memilih nama dan konvensi yang membuat maksudnya sejelas mungkin. Itu berarti Anda telah menulis kode self-documenting yang solid, dan memasukkan komentar di sana kemungkinan akan mengurangi lebih banyak daripada yang dapat membantu. (Perhatikan bahwa komentar yang berlebihan dapat benar-benar merusak keandalan kode dari waktu ke waktu dengan memperlambat ketidakselarasan dengan kode nyata dari waktu ke waktu dan dengan demikian mempersulit penguraian maksud sebenarnya.

Namun, di hampir semua program dan dalam bahasa pemrograman apa pun, Anda akan menemui titik di mana konsep dan keputusan penting tertentu yang dibuat oleh programmer asli - oleh Anda - tidak lagi terlihat dalam kode. Ini cukup banyak tidak dapat dihindari karena seorang programmer yang baik selalu memprogram untuk masa depan - yaitu, tidak hanya membuat program bekerja satu kali, tetapi untuk membuat semua perbaikan di masa depan dan versi dan ekstensi dan modifikasi dan port dan siapa yang tahu apa yang harus juga berfungsi dengan benar. Seperangkat tujuan yang terakhir jauh lebih sulit, dan membutuhkan lebih banyak pemikiran untuk melakukannya dengan baik. Juga sangat sulit untuk mengekspresikan dengan baik di sebagian besar bahasa komputer, yang lebih fokus pada fungsionalitas - yaitu, mengatakan apa yang melakukan ini versi program perlu dilakukan, saat ini, untuk membuatnya memuaskan.

Inilah contoh sederhana tentang apa yang saya maksud. Dalam kebanyakan bahasa, pencarian in-line cepat dari struktur data kecil akan memiliki kompleksitas yang cukup sehingga seseorang yang melihatnya untuk pertama kali kemungkinan tidak akan langsung mengenali apa itu. Itu adalah peluang untuk komentar yang baik, karena Anda dapat menambahkan sesuatu tentang maksud kode Anda yang mungkin akan segera dihargai oleh pembaca sebagai bantuan untuk menguraikan detail.

Sebaliknya, dalam bahasa seperti bahasa berdasarkan logika-Prolog, mengungkapkan pencarian dari daftar kecil bisa jadi sangat sepele dan ringkas bahwa setiap komentar Anda bisa menambahkan hanya akan menjadi kebisingan. Jadi, komentar yang baik tentu tergantung pada konteks. Itu termasuk faktor-faktor seperti kekuatan bahasa yang Anda gunakan dan keseluruhan konteks program.

Intinya adalah ini: Pikirkan masa depan. Tanyakan kepada diri sendiri apa yang penting dan jelas bagi Anda tentang bagaimana program harus dipahami dan dimodifikasi di masa depan. [1]

Untuk bagian-bagian dari kode Anda yang benar-benar mendokumentasikan diri, komentar cukup tambahkan noise dan tingkatkan masalah koherensi untuk versi yang akan datang. Jadi jangan menambahkannya di sana.

Tetapi untuk bagian-bagian kode Anda di mana Anda membuat keputusan kritis dari beberapa opsi, atau di mana kode itu sendiri cukup kompleks sehingga tujuannya tidak jelas, tolong, tambahkan pengetahuan khusus Anda dalam bentuk komentar. Sebuah komentar yang baik dalam kasus seperti itu adalah komentar yang membuat beberapa programmer di masa depan tahu apa yang harus dijaga tetap sama - yaitu konsep pernyataan invarian, secara kebetulan - dan apa yang boleh diubah.

[1] Ini melampaui masalah komentar, tetapi layak untuk dibahas: Jika Anda menemukan ide yang sangat tajam tentang bagaimana kode Anda dapat berubah di masa mendatang, Anda mungkin harus berpikir lebih dari sekadar membuat komentar dan menyematkan parameter-parameter itu. di dalam kode itu sendiri, karena itu akan selalu menjadi cara yang lebih dapat diandalkan untuk memastikan keandalan versi kode Anda di masa mendatang daripada mencoba menggunakan komentar untuk mengarahkan orang yang tidak dikenal di masa depan ke arah yang benar. Pada saat yang sama Anda juga ingin menghindari generalisasi yang berlebihan, karena manusia terkenal buruk dalam memprediksi masa depan, dan itu termasuk masa depan perubahan program. Jadi, cobalah untuk mendefinisikan dan menangkap dimensi masa depan yang masuk akal dan terbukti dengan baik di semua tingkat desain program, tetapi jangan

Dalam kode saya sendiri, saya akan sering meninggalkan komentar tautologi di tempat, termasuk yang sangat mengerikan seperti:

<?php
// return the result
return $result;
?>

... yang jelas berkontribusi sedikit dalam hal membuat kode lebih mudah dipahami dari perspektif penjelasan.

Namun, dalam pikiran saya, komentar-komentar ini masih memiliki nilai, jika mereka membantu menjaga konsistensi visual dari pola warna dalam stabilo sintaksis Anda .

Saya menganggap kode memiliki struktur yang sangat mirip dengan bahasa Inggris, karena ada "kalimat" dan "paragraf" (meskipun "paragraf" seluruhnya terdiri dari satu "kalimat"). Saya biasanya menyertakan ringkasan baris dan satu baris di atas setiap "paragraf". Sebagai contoh:

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE `id` = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(Abaikan kode yang tidak lengkap, suntikan SQL, dll. Anda mendapatkan ide.)

Bagi saya, komentar terakhir benar-benar menambah nilai pada kode, hanya karena itu membantu untuk secara visual menggambarkan satu "paragraf" dari yang lain dengan mempertahankan skema pewarnaan yang konsisten.

Komentar harus digunakan untuk melakukan salah satu dari yang berikut ini.

1. Informasi untuk diambil oleh pembuat dokumen. Ini tidak bisa dikecilkan, ini sangat penting.
2. Peringatan mengapa sepotong kode seperti itu, dan apa pertimbangan lainnya. Saya sudah berurusan dengan kode yang ditulis dalam 2 bahasa pemrograman. Salah satu bagian penting dari ini adalah memiliki struktur yang sama antara kedua bahasa. Komentar di kedua lokasi yang menginformasikan pengguna bahwa jika mereka mengubah nomor ini, mereka juga perlu mengubah yang lain sangat membantu.
3. Menulis catatan untuk menjelaskan mengapa sepotong kode yang tampak aneh seperti itu adanya. Jika Anda harus berpikir tentang cara mendapatkan sepotong kode untuk bekerja dengan cara tertentu, dan solusinya tidak jelas sejak awal, mungkin layak penjelasan tentang apa yang Anda coba lakukan.
4. Memberi label input / output, jika tidak jelas. Selalu baik untuk mengetahui apa yang diharapkan dari input Anda, dan apa formatnya.

Komentar tidak boleh digunakan untuk melakukan hal berikut:

1. Jelaskan hal-hal yang sangat jelas. Saya pernah kode saw warisan seperti ini: page=0; // Sets the page to 0. Saya pikir setiap individu yang kompeten dapat mengetahuinya.

Saya akan menghapus tautologi tetapi menyimpan komentar, saya akan mengomentari properti dan nama variabel dengan memberikan nilai sampel, sehingga penggunaannya dipahami dengan jelas:

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

Sekarang saya tahu persis apa yang terjadi di sana, dan dari komentar itu, saya punya ide yang jelas bagaimana menggunakannya.

Saya akan mengatakan itu tergantung pada tujuan dari komentar.

Jika mereka akan digunakan untuk menghasilkan dokumentasi untuk digunakan oleh tim yang membangunnya (atau jika mereka hanya komentar inline untuk menjelaskan sesuatu), maka saya pikir itu bisa diterima untuk meninggalkan itu. Dapat diasumsikan dengan aman bahwa itu sudah jelas; dan ketika tidak, ada anggota tim lain di dekatnya yang dapat menjelaskannya. Tentu saja, jika ternyata tidak terbukti sendiri bagi banyak orang, Anda harus menambahkannya.

Jika komentar akan menghasilkan dokumentasi untuk beberapa tim yang jauh secara geografis, maka saya akan meletakkan setiap bit dokumentasi di sana.

Saya pikir topik ini telah dibahas cukup luas dengan nama-nama seperti "komentar: anti-pola", atau "apakah komentar berbau kode?" ( satu contoh ).

Saya cenderung setuju dengan gagasan umum bahwa komentar harus menambahkan informasi baru, bukan duplikat. Dengan menambahkan komentar sepele seperti itu, Anda melanggar KERING, dan mengurangi rasio sinyal terhadap derau kode. Saya cenderung menemukan komentar tingkat tinggi yang menjelaskan tanggung jawab, alasan di balik, dan contoh penggunaan kelas jauh lebih berguna daripada komentar per-properti (terutama yang berlebihan).

Secara pribadi, dalam contoh Anda, saya akan meninggalkan komentar (jika tidak ada yang berguna untuk ditambahkan tentang properti).

Jika Anda dapat menulis kode yang tidak memerlukan komentar maka Anda telah mencapai pemrograman nirwana !.

Semakin sedikit komentar, kode Anda membutuhkan kode yang lebih baik!

Komentar seperti itu tidak berguna; apa yang saya lakukan salah?

Sepertinya tidak ada gunanya jika Anda sudah tahu apa UpdateLocation. Apakah "pembaruan" di sini adalah kata kerja atau kata benda adjunct? Yaitu, apakah ini sesuatu yang memperbarui lokasi, atau apakah itu lokasi pembaruan? Orang mungkin menyimpulkan yang terakhir dari fakta yang UpdateLocationtampaknya properti, tetapi poin yang lebih besar adalah bahwa kadang-kadang tidak ada salahnya untuk secara eksplisit menyatakan sesuatu yang tampak jelas.

Selain dokumentasi yang dikompilasi secara otomatis, kode harus mendokumentasikan dirinya sendiri, sehingga komentar hanya boleh mendokumentasikan di mana kode tidak cukup untuk mendokumentasikan dirinya sendiri.

"Lokasi" agak jelas, tetapi "Pembaruan" bisa agak kabur. Jika Anda tidak dapat menulis nama yang lebih baik, dapatkah Anda memberikan lebih banyak detail dalam komentar? Pembaruan apa? Kenapa kita perlu ini? Apa sajakah asumsi (apakah nol dibolehkan)?