Bagaimana cara menangani tautologi dalam komentar? [Tutup]


54

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?


8
Catatan: Saya akan menganggap "Lokasi pembaruan" sangat kabur kecuali tidak jelas apa "pembaruan" itu. Apakah sistem mendukung jenis URI selain URL?

34
return result # returns result
Lukas Stejskal

27
Cara menangani tautologi dalam komentar adalah cara menangani tautologi dalam komentar. (Ini adalah komentar.)
Rex Kerr

29
Ini sebenarnya bukan komentar, itu sebenarnya dokumentasi yang ditulis dalam bentuk komentar. Aturan berbeda berlaku untuk dokumentasi API daripada yang mereka lakukan untuk komentar kode inline.
Cody Gray

10
Ini hanyalah contoh Dokumentasi API yang buruk, bukan kode komentar. Format C # XML saya untuk properti seperti ini akan terlihat seperti "Mendapat atau Menetapkan Uri yang dapat digunakan untuk mengakses server pembaruan objek ini."
Kevin McCormick

Jawaban:


13

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.


+1 karena menjadi satu-satunya orang yang benar-benar memberikan komentar alternatif; bukan hanya jawaban tautologis.
Ian Boyd

Ini sebenarnya jawaban terbaik sejauh ini.
Roland Tepp

1
Dalam proyek saya saat ini, saya terkena lebih dari yang bisa saya hitung dengan kurangnya komentar pada basis kode legacy yang besar. Sesuatu yang Anda sebagai penulis, anggap sebagai metode metode yang jelas untuk sesuatu yang Anda anggap fungsionalitas yang agak jelas, mungkin tidak hanya mendokumentasikan diri dalam waktu tiga bulan ke pengembang lain. Dokumentasi tentang metode, properti, dan bidang harus mencoba menempatkan konteks pada gambaran yang lebih luas dan jawaban ini menjelaskan proses terbaik untuk mencapai tujuan itu, yang telah saya lihat sejauh ini.
Roland Tepp

1
@RolandTepp, saya benar-benar mengerti dari mana Anda berasal. Dan saya sepenuhnya setuju. Masalahnya seperti yang saya lihat adalah banyak programmer melihat komentar dan dokumentasi sebagai sesuatu yang terjadi setelah kode selesai dan siap dikirim, daripada sebagai sesuatu yang terjadi dengan kode sebagai bagian dari proses pengembangan, membutuhkan pelacakan bug dan jam dukungan bersama dengan sisa kode.
zzzzBov

54

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.


+1 - ini jawabannya! Kami tidak memerlukan komentar seperti "Deklarasi variabel", "Penghitung kenaikan" (dalam satu lingkaran) dll.
ozz

jadi dalam contoh OP, apa yang akan menjadi komentar yang bagus?
stijn

4
@stijn, saya tidak tahu - itu (jelas) hilang dari kode. Sesuatu yang hanya diketahui oleh pembuat kode tentang tujuan dan batasannya.
SK-logic

Mungkin beberapa komentar seperti // Perbarui raisShielders sesuai dengan levelOfAttack (disahkan sebagai URL)
woliveirajr

15
Pertanyaan terpenting yang harus dijawab oleh komentar adalah " WTF? "
naught101

53

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


17
+1: Saya pikir saya mengerti apa yang Anda maksud, tapi saya tidak setuju dengan apa yang Anda katakan :-) Sejauh mungkin, kode harus menggambarkan kode, sedangkan komentar harus menjelaskan alasan Anda.
Kramii Reinstate Monica

3
@ Kramii, sayangnya, kode tidak mampu menggambarkan kode, bahkan jika Anda sedang mengkode di Agda. Tidak ada bahasa yang sekuat dan ekspresif seperti bahasa alami. Dan seringkali Anda membutuhkan plot, grafik, tabel, rumus rumit untuk menggambarkan kode - hampir tidak mungkin tanpa pemrograman literasi yang tepat.
SK-logic

6
@ SK-logic: Saya tidak setuju. Metode yang panjang kurang menggambarkan diri sendiri daripada metode pendek yang memanggil serangkaian subrutin bernama.
Kramii Reinstate Monica

3
@ Kramii, maaf, saya tidak bisa melihat apa yang tidak Anda setujui dan bagaimana komentar Anda terkait dengan apa yang saya katakan. Maksud saya adalah bahwa banyak informasi harus diberikan bersama dengan kode Anda yang benar-benar hilang dari kode itu sendiri. Semua sejarah di balik keputusan yang Anda buat, semua referensi yang relevan dengan makalah, dll. - tidak ada elemen bahasa untuk mengekspresikan hal-hal seperti itu. Dan panjang / pendek metode / fungsi / subrutin / apa pun yang sama sekali tidak relevan di sini.
SK-logic

2
@ SK-logic, apa yang dikatakan Kramii berarti: "Kode harus mudah dibaca dan dimengerti sendiri" dan semua grafik dll yang Anda sebutkan termasuk dalam apa yang ia katakan sebagai: "komentar harus menggambarkan alasan Anda"
Shahbaz

36

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.


Ini jawaban terbaik. Anda harus bisa mengetahui dengan tepat properti apa yang akan digunakan ketika Anda mengkonsumsi kelas Contoh dan mengarahkan kursor ke properti.
Andy

Dalam situasi ini saya berusaha (dan sering gagal), untuk menambah setidaknya satu <remarks/>atau <see/>lebih di untuk menyediakan beberapa konten tambahan. The <summary/>masih diduplikasi, tapi komentar secara keseluruhan tidak sepenuhnya sia-sia.
earlNameless

20

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.


4
Saya tidak berpikir ada yang menganjurkan tidak menulis komentar sama sekali. Sebagian besar / semua mengatakan "tulis komentar yang sesuai", yang akan diberikan contoh UpdateLocation.
ozz

16
Uri UpdateLocation()akan ditolak oleh ulasan kode dan diubah menjadi salah satu Uri GetUpdateLocation()atau ke void UpdateLocation().
avakar

4
@avakar: Setuju dengan sentimen, tetapi karena ini adalah properti C # (dapatkan dan atur secara otomatis disintesis dan memiliki nama yang sama) penamaan ulang GetUpdateLocationakan menghasilkan kode seperti GetUpdateLocation = somelocation. LocationOfUpdateakan menjadi nama yang lebih baik, yang menghilangkan ambiguitas. Masalah dasarnya adalah bahwa OP menggunakan awalan kata kerja dan bukan kata benda. Kata kerja utama dianggap mengindikasikan tindakan suatu metode.
Semut

2
@DPD, "Berapa banyak waktu dan upaya yang diperlukan untuk memotong satu baris" berapa banyak upaya yang diperlukan untuk mempertahankannya? Berapa banyak layar yang diboroskan? Berapa banyak waktu yang dihabiskan ketika akhirnya tidak sinkron dengan kode dan mulai membingungkan pengembang?
avakar

1
Metode mengembalikan nilai, dan memiliki nama frase-kata kerja. Ini masalahnya. Itu harus memiliki nama kata benda. mis. 'Uri LocationOfUpdate ()'. Bukan GetUpdateLocation, apakah Anda mengatakan "apa GetLocation Anda?"
ctrl-alt-delor

14

/// <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) .


5

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.


3

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


3

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.


Saya mengalami kesulitan mendapatkan penyorotan sintaks untuk bekerja dalam jawaban saya di sini. Jika beberapa editor dapat datang di belakang saya dan membuatnya bekerja, saya akan sangat menghargainya, mengingat bahwa warna sangat penting untuk argumen saya.
Chris Allen Lane

Saya menambahkan Sintaks menyoroti petunjuk bahasa untuk Anda.
Paŭlo Ebermann

2

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.

2

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.


0

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.


0

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).


0

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!


3
Ini tidak mungkin (dan tidak akan pernah). Selalu ada banyak hal tertinggal kode - asumsi implisit, keputusan arsitektur, rantai panjang transformasi matematika berakhir dalam algoritma tertentu, dll.
SK-logic

1
Mungkin "Halo Dunia!" adalah programmer nirwana lalu ...
naught101

: -} - Sesuatu yang sangat jarang dicapai - intinya adalah jika Anda berjuang untuk menemukan komentar yang menambah makna maka cukup senang dengan diri sendiri itu berarti kode Anda tepat!
James Anderson

0

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.


0

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.


-1

"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)?

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.