Bisakah kode komentar menjadi dokumentasi berharga?

Saya menulis kode berikut:

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

Ada garis komentar di sini. Tapi saya pikir itu membuat kode lebih jelas, dengan memperjelas apa perbedaan antara ifdan else. Perbedaannya bahkan lebih mencolok dengan penyorotan warna.

Bisakah mengomentari kode seperti ini merupakan ide bagus?

Sebagian besar jawaban berfokus pada bagaimana memperbaiki kasus khusus ini, tetapi izinkan saya menawarkan jawaban umum mengapa kode yang dikomentari biasanya buruk:

Pertama, kode yang dikomentari tidak dikompilasi. Ini jelas, tetapi itu berarti:

1. Kode mungkin bahkan tidak berfungsi.

2. Ketika dependensi komentar berubah, itu tidak akan jelas putus.

Kode yang dikomentari sangat banyak "kode mati". Semakin lama ia duduk di sana, semakin membusuk dan memberikan semakin sedikit nilai untuk pengembang berikutnya.

Kedua, tujuannya tidak jelas. Anda benar-benar membutuhkan komentar yang lebih panjang yang memberikan konteks mengapa ada baris yang dikomentari secara acak. Ketika saya melihat hanya satu baris kode yang dikomentari, saya harus meneliti bagaimana kode itu sampai di sana hanya untuk memahami mengapa kode itu sampai di sana. Siapa yang menulisnya? Apa yang dilakukan? Apa pesan / konteks komit? Dan sebagainya.

Pertimbangkan alternatif:

• Jika tujuannya adalah memberikan contoh menggunakan fungsi / api, maka berikan uji unit. Tes unit adalah kode nyata, dan akan pecah jika tidak lagi benar.
• Jika tujuannya adalah untuk mempertahankan versi kode sebelumnya, gunakan kontrol sumber. Saya lebih suka checkout versi sebelumnya kemudian beralih komentar di seluruh basis kode untuk "mengembalikan" perubahan.
• Jika tujuannya adalah untuk mempertahankan versi alternatif dari kode yang sama, gunakan kontrol sumber (lagi). Itulah gunanya cabang.
• Jika tujuannya adalah untuk memperjelas struktur, pertimbangkan bagaimana Anda dapat menyusun ulang kode agar lebih jelas. Sebagian besar jawaban lain adalah contoh yang baik tentang bagaimana Anda melakukan ini.

Masalah terbesar dengan kode ini adalah Anda menduplikasi 6 baris itu. Setelah Anda menghilangkan duplikasi itu, komentar itu tidak berguna.

Jika Anda membuat boutiqueDao.mergeOrPersistmetode, Anda dapat menulis ulang ini sebagai:

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

Kode yang membuat atau memperbarui objek tertentu adalah umum, jadi Anda harus menyelesaikannya sekali, misalnya dengan membuat mergeOrPersistmetode. Anda tentu tidak boleh menduplikasi semua kode tugas untuk kedua kasus tersebut.

Banyak ORM telah membangun dukungan untuk ini dalam beberapa cara. Misalnya mereka mungkin membuat baris baru jika idnol, dan memperbarui baris yang ada jika idbukan nol. Bentuk persisnya tergantung pada ORM yang dimaksud, dan karena saya tidak terbiasa dengan teknologi yang Anda gunakan, saya tidak dapat membantu Anda dengan itu.

Jika Anda tidak ingin membuat mergeOrPersistmetode, Anda harus menghilangkan duplikasi dengan cara lain, misalnya dengan memperkenalkan isNewBoutiquebendera. Itu mungkin tidak cantik, tetapi masih jauh lebih baik daripada menduplikasi seluruh logika tugas.

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

Ini adalah ide yang sangat mengerikan . Tidak jelas apa tujuannya. Apakah pengembang berkomentar secara tidak sengaja? Untuk menguji sesuatu? Apa yang sedang terjadi?!

Selain dari kenyataan bahwa saya melihat 6 baris yang benar-benar sama dalam kedua kasus. Sebaliknya, Anda harus mencegah duplikasi kode ini. Maka akan lebih jelas bahwa dalam satu kasus Anda juga memanggil setSelected.

Tidak, itu ide yang buruk. Berdasarkan potongan kode itu, pikiran-pikiran berikut muncul di benak saya:

• Baris ini dikomentari karena pengembang sedang men-debug-nya dan lupa mengembalikan jalur ke keadaan semula
• Baris ini dikomentari karena dulu merupakan bagian dari logika bisnis, tetapi tidak lagi demikian
• Baris ini dikomentari karena menyebabkan masalah kinerja pada produksi dan pengembang ingin melihat apa dampaknya pada sistem produksi

Setelah melihat ribuan baris kode komentar, saya sekarang melakukan satu-satunya hal yang masuk akal ketika saya melihatnya: Saya segera menghapusnya.

Tidak ada alasan masuk akal untuk memeriksa kode yang dikomentari ke dalam repositori.

Selain itu, kode Anda menggunakan banyak duplikasi. Saya sarankan Anda mengoptimalkan itu untuk keterbacaan manusia sesegera mungkin.

Saya hanya ingin menambahkan jawaban CodesInChaos, dengan menunjukkan bahwa Anda dapat melakukan refactor lebih lanjut menjadi metode kecil . Berbagi fungsionalitas umum dengan komposisi menghindari persyaratan:

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

Meskipun ini jelas bukan kasus yang baik untuk kode komentar ada situasi yang saya pikir menjamin:

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

Ini peringatan bagi siapa pun yang melihatnya nanti bahwa perbaikan yang jelas tidak.

Sunting: Saya sedang berbicara tentang sesuatu yang kecil. Jika besar, Anda menjelaskannya.

Dalam contoh khusus ini, saya menemukan kode yang dikomentari sangat ambigu, sebagian besar karena alasan yang diuraikan dalam jawaban Dibkke . Yang lain telah menyarankan cara-cara Anda dapat memperbaiki kode untuk menghindari godaan untuk melakukan hal ini, meskipun, jika itu tidak memungkinkan untuk beberapa alasan (misalnya, garis-garisnya serupa, tetapi tidak cukup dekat), saya akan menghargai komentar seperti:

// Tidak perlu membatalkan pilihan butik ini, karena [APA PUN]

Namun, saya pikir ada beberapa situasi di mana meninggalkan (atau bahkan menambahkan komentar) kode tidak tercela. Ketika menggunakan sesuatu seperti MATLAB atau NumPY, kita sering dapat menulis kode yang sama yang 1) berulang di atas array, memproses satu elemen pada satu waktu atau 2) mengoperasikan seluruh array sekaligus. Dalam beberapa kasus, yang terakhir jauh lebih cepat, tetapi juga jauh lebih sulit dibaca. Jika saya mengganti beberapa kode dengan vektor yang setara, saya menyematkan kode asli dalam komentar terdekat, seperti ini:

%% Kode vektor di bawah ini melakukan ini:

% for ii in 1:N
%    for jj in 1:N
%      etc.

% tetapi versi matriks berjalan ~ 15x lebih cepat pada input tipikal (MK, 03/10/2013)

Jelas, kita perlu berhati-hati bahwa kedua versi benar-benar melakukan hal yang sama dan bahwa komentar tetap sinkron dengan kode aktual atau dihapus jika kode berubah. Jelas, peringatan biasa tentang optimasi prematur juga berlaku ...

Satu-satunya saat saya melihat kode commented-out yang berguna adalah file config, di mana kode untuk setiap opsi disediakan, tetapi berkomentar, membuatnya mudah untuk mengaktifkan pengaturan dengan hanya menghapus penanda komentar:

## Enable support for mouse input:
# enable_mouse = true

Dalam hal ini, kode yang dikomentari membantu untuk mendokumentasikan semua opsi yang tersedia, dan bagaimana menggunakannya. Ini juga konvensional untuk menggunakan nilai-nilai default di seluruh, sehingga kode ini juga mendokumentasikan pengaturan default.

Secara umum, kode hanya mendokumentasikan diri sendiri untuk orang yang menulis kode. Jika dokumentasi diperlukan, tulis dokumentasi. Tidak dapat diterima untuk mengharapkan pengembang baru ke basis kode sumber akan duduk membaca ribuan baris kode untuk mencoba mencari tahu dari tingkat tinggi apa yang terjadi.

Dalam hal ini, tujuan dari baris kode yang dikomentari adalah untuk menunjukkan perbedaan antara dua contoh kode duplikat. Alih-alih mencoba mendokumentasikan perbedaan secara halus dengan komentar, tulis ulang kode sehingga masuk akal. Kemudian, jika Anda masih merasa perlu mengomentari kodenya, tulis komentar yang sesuai.

Tidak, kode yang dikomentari menjadi basi, dan segera lebih buruk daripada tidak berharga, sering kali berbahaya, karena memperkuat beberapa aspek implementasi, bersama dengan semua asumsi saat ini.

Komentar harus mencakup detail antarmuka dan fungsi yang dimaksudkan; "fungsi yang dimaksudkan": dapat mencakup, pertama kita coba ini, lalu kita coba itu, lalu kita gagal dengan cara ini.

Programmer yang saya lihat mencoba untuk meninggalkan hal-hal dalam komentar hanya cinta dengan apa yang mereka tulis, tidak ingin kehilangan itu, bahkan jika itu tidak menambahkan apa pun ke produk jadi.

Ini bisa dalam kasus yang sangat jarang, tetapi tidak seperti yang Anda lakukan. Jawaban-jawaban lain cukup baik untuk menjelaskan alasannya.

Salah satu kasus yang jarang terjadi adalah spec template RPM yang kami gunakan di toko saya sebagai titik awal untuk semua paket baru, sebagian besar untuk memastikan tidak ada yang penting yang ditinggalkan. Sebagian besar, tetapi tidak semua paket kami memiliki tarball yang berisi sumber-sumber yang memiliki nama standar dan ditentukan dengan tag:

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

Untuk paket tanpa sumber, kami mengomentari tag dan memberikan komentar lain di atasnya untuk mempertahankan format standar dan menunjukkan bahwa seseorang telah berhenti dan memikirkan masalah sebagai bagian dari proses pengembangan:

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

Anda tidak menambahkan kode yang Anda tahu tidak akan digunakan karena, seperti yang telah dibahas orang lain, itu bisa saja keliru untuk sesuatu yang ada di sana. Bisa. namun, berguna untuk menambahkan komentar yang menjelaskan mengapa kode yang diharapkan ada ada yang hilang:

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

Kode yang dikomentari tidak digunakan oleh aplikasi, jadi perlu disertai dengan komentar lebih lanjut yang menyatakan mengapa tidak digunakan. Tapi dalam konteks itu, ada yang situasi di mana kode komentar-out dapat berguna.

Apa yang terlintas dalam pikiran saya adalah kasus di mana Anda memecahkan masalah menggunakan pendekatan umum dan menarik, tetapi kemudian ternyata persyaratan dari masalah Anda yang sebenarnya sedikit berbeda dari masalah itu. Terutama jika persyaratan Anda ternyata membutuhkan lebih banyak kode, godaan bagi pengelola untuk "mengoptimalkan" kode menggunakan pendekatan lama kemungkinan akan kuat, tetapi melakukan itu hanya akan membawa bug kembali. Menjaga implementasi "salah" di dalam komentar akan membantu menghilangkan ini, karena Anda dapat menggunakannya untuk menggambarkan mengapa pendekatan itu salah dalam situasi ini.

Ini bukan situasi yang bisa saya bayangkan terjadi sangat sering. Biasanya, itu harus cukup untuk menjelaskan hal-hal tanpa menyertakan contoh "salah" implementasi. Tapi saya bisa membayangkan kasus di mana itu tidak cukup, jadi karena pertanyaannya adalah apakah itu bisa berguna, ya, itu bisa. Hanya tidak sebagian besar waktu.

Ini tidak terlihat teman baik.

Kode yang dikomentari adalah ... hanya bukan kode. Kode adalah untuk implementasi logika. Membuat kode lebih mudah dibaca dengan sendirinya adalah seni. Seperti @CodesInChaos sudah menyarankan bahwa baris kode berulang tidak implementasi logika yang sangat baik .

Apakah Anda benar-benar berpikir bahwa satu programmer sejati akan lebih memilih keterbacaan daripada implementasi logis. (Ngomong-ngomong, kami memiliki komentar dan 'pelengkap' untuk dimasukkan ke dalam representasi logis kami).

Sejauh yang saya ketahui orang harus menulis kode untuk kompiler dan itu bagus - jika 'itu' memahami kode itu. Untuk keterbacaan manusia Komentar baik untuk pengembang (dalam jangka panjang), untuk orang-orang yang menggunakan kembali kode itu (mis. Penguji).

Kalau tidak, Anda dapat mencoba sesuatu yang lebih fleksibel di sini, sesuatu seperti

boutique.setSite (situs) dapat diganti dengan

setsiteof.boutique (situs). Ada berbagai aspek dan perspektif OOP yang melaluinya Anda dapat meningkatkan keterbacaan.

Sementara kode ini tampaknya sangat menarik pada awalnya dan orang dapat berpikir bahwa ia telah menemukan cara untuk keterbacaan manusia sementara kompiler juga melakukan tugasnya dengan sempurna, dan kita semua mulai mengikuti praktik ini, itu akan mengarah ke file fuzzy yang akan menjadi kurang dapat dibaca. dalam waktu dan lebih kompleks karena akan memperluas jalannya ke bawah.