Apa saja contoh komentar yang memberi tahu Anda alasannya alih-alih bagaimana atau apa? [Tutup]


78

Pertama-tama, dalam pertanyaan ini saya ingin menjauh dari polemik apakah komentar kode sumber itu baik atau buruk. Saya hanya mencoba memahami dengan lebih jelas apa yang dimaksud orang ketika mereka berbicara tentang komentar yang memberi tahu Anda MENGAPA, APA atau BAGAIMANA.

Kita sering melihat pedoman seperti "Komentar harus memberi tahu MENGAPA; kode itu sendiri harus memberi tahu Anda BAGAIMANA". Sangat mudah untuk menyetujui pernyataan pada tingkat abstrak. Namun, orang biasanya menjatuhkan ini seperti dogma, dan meninggalkan ruangan tanpa penjelasan lebih lanjut. Saya telah melihat ini digunakan di banyak tempat dan konteks yang berbeda, sehingga sepertinya orang-orang dapat menyetujui slogannya, tetapi mereka tampaknya berbicara tentang hal-hal yang berbeda sama sekali.

Jadi, kembali ke pertanyaan: jika komentar harus memberi tahu MENGAPA, mengapa ini MENGAPA kita bicarakan? Apakah ini alasan mengapa potongan kode itu ada di tempat pertama? Apakah ini yang harus dilakukan oleh kode bagian itu? Saya akan sangat menghargai jika seseorang dapat memberikan penjelasan yang jelas, dan kemudian menambahkan beberapa contoh yang baik (contoh buruk tidak benar-benar diperlukan, tetapi jatuh bebas untuk menambahkannya sebagai kontras).

Ada banyak pertanyaan tentang apakah komentar itu baik atau buruk, tetapi tidak ada yang menjawab pertanyaan spesifik tentang apa contoh komentar yang baik yang memberi tahu Anda MENGAPA.


36
Terkadang komentar terbaik membahas MENGAPA TIDAK. Saya pernah menemukan sedikit kode kompleks yang terlihat seperti itu dapat dengan mudah disederhanakan. Komentar tersebut menjelaskan mengapa penyederhanaan yang jelas itu tidak berfungsi dalam contoh khusus ini (karena pengembang asli sudah mencobanya).
Dan Pichelman

6
There are many questions on whether comments are good or bad, but no one that addresses the specific question of what are good examples of comments that tell you WHY. Jika semua orang memberikan contoh yang valid, maka mereka semua adalah jawaban yang benar. Format situs web ini adalah untuk memfasilitasi proses tanya jawab di mana tidak semua jawaban dibuat sama.
David Kaczynski

Poin bagus, @ david-kaczynski. Apa yang Anda sarankan?
rick

1
Dari atas kepala saya, saya tidak bisa memikirkan cara untuk mengucapkan pertanyaan sehingga satu contoh atau taktik umum dapat menjadi jawaban "terbaik". Ada bagian obrolan dari p.se: chat.stackexchange.com/rooms/21/the-whiteboard , tetapi mungkin akan ada forum yang lebih baik di luar sana untuk pertanyaan Anda. Dalam semua keadilan, sepertinya pertanyaan Anda menerima respons positif dari komunitas di sini, jadi mungkin tidak perlu dikhawatirkan. Saran terbaik yang dapat saya berikan untuk menemukan contoh komentar yang bermanfaat adalah menelusuri repositori publik git yang populer.
David Kaczynski

Jawaban:


62

Contoh paling umum dan paling khas adalah komentar di sekitar berbagai solusi. Misalnya yang ini:

https://github.com/git/git/blob/master/compat/fopen.c :

/*
 *  The order of the following two lines is important.
 *
 *  FREAD_READS_DIRECTORIES is undefined before including git-compat-util.h
 *  to avoid the redefinition of fopen within git-compat-util.h. This is
 *  necessary since fopen is a macro on some platforms which may be set
 *  based on compiler options. For example, on AIX fopen is set to fopen64
 *  when _LARGE_FILES is defined. The previous technique of merely undefining
 *  fopen after including git-compat-util.h is inadequate in this case.
 */
#undef FREAD_READS_DIRECTORIES
#include "../git-compat-util.h"

Anda pasti akan menemukan lebih banyak contoh di sumber Git dan Linux; kedua proyek mencoba mengikuti aturan ini.

Saya juga merekomendasikan untuk mengikuti aturan ini bahkan lebih ketat dengan log komit . Untuk komentar kode mungkin saja Anda memperbaiki kode, tetapi lupa memperbarui komentar. Dengan jumlah kode dalam proyek biasa, dijamin akan terjadi cepat atau lambat. Di sisi lain, log komit terkait dengan perubahan tertentu dan dapat dipanggil kembali menggunakan fungsionalitas "anotasi" / "menyalahkan" sistem kontrol versi. Lagi-lagi Git dan Linux punya beberapa contoh bagus.

Lihat misalnya di komit ini . (tidak menyalin di sini, terlalu lama). Ini memiliki empat paragraf mengambil hampir seluruh halaman (dan sedikit di atas layar) menggambarkan apa sebenarnya yang salah dan mengapa itu salah dan terus berjalan dan memodifikasi semua garis SIX whoping. Mereka menggunakan komentar seperti ini untuk dua tujuan:

  1. Semua perubahan yang diajukan ditinjau dan log komit adalah yang harus menjelaskan perubahan tersebut kepada peninjau.
  2. Ketika bug ditemukan, log yang relevan diambil menggunakan "beliung" atau "menyalahkan" untuk menghindari kembali ke perilaku yang sebelumnya juga salah.

(catatan: saya butuh paling banyak 10 menit browsing acak dari repo git untuk mendapatkan dua contoh ini, jadi pasti akan mudah untuk menemukan lebih banyak di sana)


29

Sebuah komentar yang memberi tahu Anda alasan menjelaskan alasan di balik kode - misalnya:

// We need to sync the values if the temp <doodad> GUID matches one of the active <doodad>'s
// GUID, as the temp <doodad> has the most recent values according to the server and said 
// values might have changed since we added the <doodad>. We want a user to be able to <foo> 
// the <doodad> whenever, which means those values must be accurate.
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

Sebuah komentar yang memberi tahu Anda bagaimana menjelaskan apa yang dilakukan kode.

// Loop through our <doodads> and check for a GUID match. If it matches, copy the new values
// on the <doodad> that matches 
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

Perbedaannya adalah seorang pengelola dapat melihat yang pertama dan berkata, "Oh, jadi ini mungkin ketinggalan zaman!" Dalam kasus kedua, pengelola kata memiliki komentar yang tidak memberi tahu Anda apa pun yang kode itu sendiri tidak ungkapkan (dengan asumsi nama variabel baik).

Berikut adalah contoh nyata dari komentar mengapa, dari beberapa kode iOS yang saya kerjakan di mana kami perlu mendapatkan alamat gateway (atau tebakan yang masuk akal untuk itu). Saya bisa saja meninggalkan komentar yang mengatakan hal-hal seperti "Inisialisasi soket penerima," tapi itu hanya akan memberitahu pengelola (atau calon saya) apa yang terjadi, bukan mengapa saya harus melakukan kludge aneh ini untuk mendapatkan alamat gateway di tempat pertama.

/*
 We're going to do something really hacky here and use a custom partial
 implementation of traceroute to get our gateway IP address.

 [rant removed - irrelevant to the point]

 There's no good way to get at the gateway address of an iDevice
 right now. So, we have two options (per https://devforums.apple.com/message/644915#644915 ):
 1. Get at and parse the routing table (like netstat -rn, or route -n)
 2. Do a traceroute and grab the IP address for the first hop

 As far as I can tell, the former requires <sys/route.h> from the Mac OS X
 header files, which doesn't seem like a good idea to me. Also, there's a
 thread on the Apple Developer forums that seems to imply that header isn't
 in iOS for a reason (https://devforums.apple.com/message/774731#774731 ).

 So when we send our request with a TTL of one it will survive a single hop
 to the router and return, triumphant, with the router's IP address!

 Viva la kludge!

 PS: Original source was the below SO question, but I've modded it since then.
 http://stackoverflow.com/questions/14304581/hops-tracing-ttl-reciveform-on-ios/14304923#14304923
 */

// Default to using Google's DNS address. We used to try checking www.google.com
// if reachability reported we had internet, but that could still hang on routers
// that had no internet connectivity - not sure why.
const char *ip_addr = [kGoogleDNS UTF8String]; // Must be const to avoid undefined behavior
struct sockaddr_in destination,fromAddr;
int recv_sock;
int send_sock;

// ... more code follows

4
Contoh pertama adalah terlalu banyak bertele-tele dan mencakup banyak "bagaimana". Seharusnya hanya mengatakan "Perbarui <oodad> dari temp <doodad> sehingga pengguna dapat dengan aman <foo> kapan saja." Sisanya sepele untuk menyiratkan dari ini atau kode. Juga "pengantar dongeng" dalam empat paragraf pertama dari contoh terakhir sama sekali tidak ada gunanya. Saya akan meninggalkan "Viva la kludge!"; itu lucu dan pada akhirnya. Tetapi awalnya terlalu banyak kata yang harus digali sebelum mendapatkan penjelasan yang sebenarnya.
Jan Hudec

@ JanHudec Disesuaikan sesuai umpan balik Anda. Terlihat benar?
thegrinner

15
Salah satu hal yang menyenangkan tentang contoh kedua adalah tidak hanya menjelaskan mengapa kode bekerja dengan cara tertentu, tetapi juga menjelaskan mengapa alternatif lain yang masuk akal tidak diambil. Ini membuat kode jauh lebih mudah dikelola, karena orang berikutnya yang membaca kode dan berpikir, "Mengapa saya tidak bisa hanya menguraikan tabel routing?" bisa langsung baca komentar. Selanjutnya, seseorang yang tidak datang dengan alasan yang sah untuk mengubah kode akan lebih percaya diri bahwa aman untuk melakukannya. Jika tidak, pengelola tetap takut bahwa perubahan apa pun akan gagal dalam skenario (tidak diketahui) yang menginspirasi kludge.
Brian

18

Saya ingin memulai jawaban saya dengan kutipan yang dibuat oleh Jeff Atwood dalam posting Blog-nya Code Tells You How, Comments Tell You Why :

jenis komentar terbaik adalah yang tidak Anda butuhkan

Dia juga menyatakan bahwa:

Pertama-tama Anda harus berusaha membuat kode sesederhana mungkin untuk dipahami tanpa mengandalkan komentar sebagai penopang. Hanya pada titik di mana kode tidak dapat dibuat lebih mudah dipahami, Anda harus mulai menambahkan komentar.

Saya sepenuhnya setuju dan pada titik ini saya harus menambahkan bahwa sebelum saya dapat mulai membuat kode sesederhana mungkin saya membuat kode berfungsi dan kemudian mulai refactoring. Jadi selama menjalankan pertama sebelum refactoring menambahkan mengapa komentar sangat membantu.

Sebagai contoh jika menggunakan loop 3 bersarang dengan hashtable 2 dimensi untuk mengisi tabel hari kerja sambil mem-parsing data, sangat mudah untuk kehilangan jejak apa yang dilakukan oleh seseorang atau bahkan diri Anda sendiri jika tidak melihat selama beberapa minggu dan tiba-tiba refactoring.

[loop1]6oclock -> [loop2]Monday -> [loop3]stage 1 to 4
         -> tuesday-> stage 1 to 4
         ...
         -> Saturday -> stage 1 to 4
    7oclock -> Monday-> stage 1 to 4
        ....etc.

Bagian atas adalah contoh bagaimana 3 loop bersarang akan bekerja sebelum refactoring.
Juga menjelaskan beberapa kondisi cabang dapat membantu memahami kode lebih baik dengan apa yang dipikirkan seseorang dalam proses:

// added a zero before the actual day in order for the days always to be 2 digits long.
if( actualDayFuture < 10 ) 
{ 
     actualDayFuture = padIfSingleDigitDate(actualDayFuture); 
}

Bahkan kode yang sederhana dan jelas berfungsi baik dengan komentar. Hanya untuk membuat hal-hal sedikit lebih jelas, lebih jelas atau lebih mudah dipahami oleh rekan kerja dan bahkan untuk diri Anda sendiri dalam memelihara perangkat lunak.

Tentu xp menyatakan memiliki kode yang menjelaskan sendiri, tetapi apakah komentar satu baris sakit?

Saya juga menemukan aturan berikut dari blog ini sangat membantu:

  • Pahami materi sebelum Anda menulis
  • Tulis seolah-olah audiens Anda adalah siswa kelas empat
  • Pikirkan tentang bagaimana pembaca bisa salah menafsirkan Anda

Siapa pun yang harus kembali ke kode mereka sendiri atau orang lain atau bahkan kode warisan tahu bahwa itu bisa menjadi sakit kepala. Jadi, alih-alih menjadi malas atau mencoba menjadi uber-coder dalam tidak berkomentar apa-apa atau sangat sedikit, mengapa tidak membuat sendiri atau beberapa bugger miskin, yang harus menjaga kode Anda, kehidupan masa depan jauh lebih mudah dengan mengikuti aturan yang dikutip.

Juga banyak keputusan pemrograman dibuat diragukan selama ulasan dan tidak selalu jelas mengapa beberapa bagian ditulis seperti itu bahkan jika beberapa bagian kode penting untuk program untuk bekerja karena bug utama ditemukan karena kode tersebut digunakan selama bertahun-tahun . Jadi agar tidak membuat Anda bosan semua benar-benar dengan tl sebuah; dr dekat dengan kutipan terakhir dari acmqueue :

Dokumentasi sebelumnya, jelas, dan luas adalah elemen kunci dalam menciptakan perangkat lunak yang dapat bertahan dan beradaptasi. Mendokumentasikan dengan standar tinggi akan mengurangi waktu pengembangan, menghasilkan pekerjaan yang lebih baik, dan meningkatkan laba. Sulit untuk meminta lebih dari itu dari teknik apa pun.


8
Dalam contoh kedua Anda, seseorang dapat menghilangkan komentar sama sekali dengan refactoring: actualDayFuture = padIfSingleDigitDate (actualDayFuture); Ini sepele, tetapi contoh yang lebih kuat akan mendapat manfaat dari pendekatan ini.
Chris Cudmore

4
Saya akan memindahkan persyaratan ke dalam metode juga. - Sekali lagi, bukan untuk sesuatu yang sepele, tetapi memungkinkan saya untuk mengabaikan pemikiran tentang logika padding sama sekali. Saya tidak akan mengganti contoh asli Anda, karena ini adalah jawaban yang lebih baik untuk pertanyaan itu. Ini lebih dari catatan, mengeksplorasi alternatif lain.
Chris Cudmore

1
Ad "Tentu xp menyatakan memiliki kode yang menjelaskan sendiri, tetapi apakah komentar satu baris sakit?": Komentar baik, tetapi ada juga bahaya komentar berlebihan. Setiap baris komentar adalah salah satu yang seseorang mungkin lupa untuk memperbarui ketika mereka mengubah kode.
Jan Hudec

1
Cara yang lebih baik untuk mengatakan ini adalah "Jenis komentar terbaik adalah tidak adanya kebutuhan akan komentar". Komentar yang tidak diperlukan (tapi tetap ditulis) bukan komentar yang baik
Kaz

1
Menarik bahwa kode yang dirujuk int directionCode = (x > oldX) ? DIRECTIONCODE_RIGHT : (x > oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;salah. Tentu saja harus ... (x < oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;. Gagasan komentar bagus - kode buruk.
chux

8

Saya cenderung mengurangi komentar menjadi referensi di mana fungsi / kode tertentu dijelaskan lebih menyeluruh atau untuk menjelaskan mengapa cara pemrograman tertentu dipilih.

Mengingat bahwa programmer lain yang memiliki keahlian serupa menggunakan atau membaca kode Anda, penting untuk berkomentar jika Anda menggunakan cara yang berbeda dari yang diharapkan untuk mencapai sesuatu. Jadi Anda bisa menjelaskan dalam komentar mengapa Anda memilih cara ini.

Misalnya, jika Anda dapat menggunakan dua sensor yang berbeda pada perangkat Android dan salah satunya tidak sesuai dengan kebutuhan Anda, Anda dapat menjelaskan dalam komentar mengapa Anda memilih yang lainnya.

Jadi 'mengapa' harus memberikan alasan pada pilihan yang Anda buat.


5
Referensi adalah contoh yang bagus. // Metode ini menggunakan algoritma furshclingeheimer untuk mengubah bentuk foobit. Lihat http: // ...
Chris Cudmore

8

Komentar harus memberi tahu Anda apa yang kode tidak, tidak perlu dihilangkan oleh MENGAPA , BAGAIMANA , atau APA . Jika Anda memiliki nama yang bagus dan memiliki fungsi yang digambarkan dengan baik, sangat mungkin bahwa kode dapat memberi tahu Anda dengan tepat apa yang sedang terjadi. Sebagai contoh:

List<LightMap> maps = makeLightmaps(receivingModels);
TrianglePartitioner partition = new Octree(castingTriangles);
List<Photon> photons = firePhotons(lights, partition);

if (photons.Count > 0)
{
      PhotonPartitioner photonMap = new KDTree(photons);
      gatherPhotons(maps, photonMap, partition, lights);
}

Kode ini benar-benar tidak perlu komentar. Fungsi dan nama ketik membuatnya mudah dimengerti.

Namun, kadang-kadang, bisa sulit atau tidak mungkin untuk benar-benar membuat kode lancar seperti di atas. Misalnya, potongan kode berikutnya adalah untuk menemukan titik acak statistik pada sebuah bola. Matematikanya cukup buram, jadi komentar dengan tautan ke penjelasannya adalah membantu memberi tahu BAGAIMANA cara kerjanya. Ini dapat dibungkus dalam fungsi untuk memberi tahu APA yang dilakukannya tanpa perlu komentar jika diperlukan lebih dari sekali, jika tidak, judul tautan juga membantu di departemen itu.

double randomA = localGenerator.NextDouble();
double randomB = localGenerator.NextDouble();

//http://mathworld.wolfram.com/SpherePointPicking.html
double theta = 2 * Math.PI * randomA;
double phi = Math.Acos(2 * randomB - 1);

Vector3 randomDirection = new Vector3(Settings.ambientRayLength * (float)(Math.Cos(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)(Math.Sin(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)Math.Cos(phi));

Contoh lain ketika komentar memberi tahu Anda apa kode tidak untuk menjelaskan keputusan. Dalam contoh berikut, kode tidak mengunci variabel non-thread-lokal di dalam sepotong kode berulir. Ada alasan untuk ini dan komentar menjelaskan MENGAPA . Tanpa komentar, itu bisa dianggap bug, atau bahkan tidak diperhatikan.

Random random = new Random();
Parallel.For(0, maxPhotons, delegate(int photonIndex, ParallelLoopState state)
{
    ...
    //I don't actually care if this random number is unique between threads, threadsafty is not that big of a deal
    //  in this case and locking the random object could cause a lot of lock contention
    while (random.NextDouble() > reflectProbability)
    {
        ...
    }
    ...
}

Mungkin, bisa ditingkatkan untuk mengatakan mengapa objek acak tidak dibuat di dalam loop paralel di tempat pertama. Jika tidak ada alasan, itu juga bisa membuat seseorang datang dan menyadari bahwa seluruh ide itu bodoh dan merupakan tempat yang baik untuk refactoring.


Apakah masuk akal untuk menggambarkan kode sebagai tidak memerlukan komentar ketika komentar didahului oleh WriteTextbukan //?

1
Seperti yang saya katakan dalam jawaban, komentar tidak diperlukan bahkan jika tidak ada pernyataan cetak, namun saya telah mengeditnya untuk menghapus pernyataan cetak untuk membuat poin lebih jelas.
Chewy Gumball

5

Mungkin bermanfaat untuk mengenali berbagai jenis "mengapa" - terutama:

  • Alasan bahwa kode yang tampak terlalu rumit tidak akan berfungsi jika disederhanakan (mis. Tipecast yang tampaknya berlebihan mungkin diperlukan untuk memastikan bahwa kode berfungsi dalam beberapa kasus sudut).

  • Alasan bahwa beberapa operasi sederhana tertentu yang terlihat berbahaya sebenarnya aman (mis. "Rutinitas pengambilan data kami akan melaporkan item dummy item melewati yang terakhir lebih kecil dari yang lainnya, dan item setelah itu lebih besar; item apa pun yang harus diurutkan sebelum yang lain, dalam urutan naik atau turun yang konsisten, akan memiliki setidaknya satu item lagi (mungkin boneka) mengikutinya ").

Dalam banyak kasus, komentar tipe kedua di satu bagian kode dapat "cocok" dengan komentar tipe pertama di bagian lain (mis. "Walaupun kelihatannya urutan operasi ini dapat disederhanakan, rutin Fitz bergantung pada Wongle tidak sedang Woozled sampai setelah Bandersnatch telah Blarped. ")


2

Jangan lupa, jika Anda menulis sebuah program, Anda tidak hanya mengetik secara acak, Anda melakukannya karena Anda memiliki model yang Anda inginkan , apakah itu dalam dokumen formal atau hanya di kepala Anda. Hal-hal yang ada di kepala Anda sama nyatanya dengan perangkat lunak / data di komputer (dan kemungkinan mengandung bug).

Seseorang yang membaca kode Anda mungkin tidak memiliki model itu di kepalanya, sehingga komentar dapat berfungsi untuk memberi tahu mereka apa model itu dan bagaimana kode terkait dengan itu. Saya pikir itulah yang dimaksud dengan "mengapa". Tentu saja baik untuk membuat kode itu sendiri sejelas mungkin, tetapi itu tidak selalu cukup baik. Contoh:

// transform the x,y point location to the nearest hexagonal cell location
ix1 = (int)floor(0.5 + x + y/2);
iy1 = (int)floor(0.5 + y);

Selain itu, model berubah seiring waktu, dan perubahan itu harus ditransfer ke kode. Jadi komentar tidak hanya perlu mengatakan "mengapa" ada sesuatu dalam kode, tetapi sama pentingnya bagaimana mengubahnya sebagai respons terhadap perubahan model yang diantisipasi. Contoh:

// to change to square cell locations, remove the "+ y/2" in the above code

Saya pikir tujuan komentar terkadang diabaikan.


2
Pertanyaannya adalah meminta contoh. Bisakah Anda menambahkan contoh untuk membuat jawaban ini lebih bermanfaat?
Bryan Oakley

2
Potongan kode pertama terlihat seperti contoh klasik menjelaskan "apa," bagi saya. Bukannya itu komentar yang buruk, tapi saya pikir itu tidak menjawab pertanyaan OP.

@ Jon: Jika komentar itu tidak ada, pembaca dapat melihat apa yang terjadi, tetapi tidak tahu mengapa.
Mike Dunlavey

1
@MikeDunlavey: Saya tidak setuju. Saya masih tidak tahu - mengapa Anda ingin lokasi sel heksagonal terdekat? Apa tujuan mendapatkan lokasi ini? Apakah akan memengaruhi apa pun jika saya menghapus dua baris ini?

2

Tidak semua komentar saya adalah tipe 'mengapa', tetapi banyak.
Ini adalah contoh dari satu file sumber (Delphi):

// For easier access to the custom properties:

function GetPrivate: Integer;   // It's an integer field in the external program so let's treat it like that here

// The below properties depend on the ones above or are calculated fields.
// They are kept up-to-date in the OnEventModified event of the TTSynchronizerStorage
// or in the ClientDataSet.OnCalcFields of the TcxDBSchedulerStorage.DataSource.DataSet
property IsModified       : Boolean   read GetIsModified   write SetIsModified;
property IsCatTT          : Boolean   read GetIsCatTT      write SetIsCatTT;
property IsSynced         : Boolean   read GetIsSynced     write SetIsSynced;

lLeftPos := pos(' - [',ASubject); // Were subject and [shiftnaam:act,project,cust] concatenated with a dash?

// Things that were added behing the ] we will append to the subject:

// In the storage the custom value must also be set for:
Self.SetCustomFieldValueByname(cCustFldIsCatTT,Result);

// When we show the custom fields in a grid, the Getters are not executed,
// because the DevEx code does not know about our class helpers.
// So we have two keep both properties synchronized ourselves:

// lNewMasterEvent was set to usUpdated, overwrite because we added:
if ARepair then
  lNewMasterEvent.CustUpdateStatus := usRecreated

// The source occurrence date may have bee changed. Using GetOriginalDate we can retrieve the original date,
// then use that for creating a target occurrence (and update its date):

lNewTTOccurrence.CustSyncEntryID := cSyncEntryID0;    // Backward compatibility with old sync methode

// Single event became recurring or vice versa; replace entire event

// In contradiction to CopySingleEventToTimeTell, CopyMasterEventToTimeTell does not have a ANewStatus parameter
// because master events are always added.

Perhatikan bahwa (saya) mengapa komentar biasanya mendahului kode yang akan melakukannya (karenanya diakhiri dengan titik dua).

Saya memiliki beberapa komentar yang hanya menjelaskan apa yang sedang terjadi, misalnya ketika suatu proses memiliki banyak langkah yang memiliki pengelompokan logis (dan kode tidak direfaktor untuk menunjukkannya secara otomatis), saya akan berkomentar seperti:

// Step 1. Initialization

1

Saya memahami MENGAPA sebagai alasan mengapa Anda melakukan sesuatu dengan cara yang mungkin aneh atau mungkin tidak logis, karena keadaan tertentu yang mengharuskannya melakukannya. The BAGAIMANA dapat dilihat pada kode itu sendiri, tidak peduli seberapa aneh itu, bahkan jika kode tidak membuat "rasa". The APA mungkin terbaik kepada pada awal dokumentasi kelas / fungsi. Sehingga membuat Anda menambahkan MENGAPA , di mana Anda menjelaskan apa pun yang tidak termasuk dalam BAGAIMANA dan APA, dan cara-cara aneh yang perlu Anda ambil karena alasan di luar kendali Anda.

Tentu saja tidak selalu demikian, di luar negeri unicorn dan pelangi ...

BAGAIMANA:

foreach($critters as $creature) {
   $creature->dance();
}

APA:

/* Dancing creatures v1.0
 * 
 * The purpose of this is to make all your critters do the funky dance.
 */

foreach($critters as $creature) {
  $creature->dance();
}

MENGAPA:

// We had to store the items in an array of objects because of _____ (reason)
foreach($critters as $creature) {
   $creature->dance();
}

5
bagaimana ini menjawab pertanyaan yang diajukan?
nyamuk

1
Mengutip OP: "Jadi, kembali ke pertanyaan: jika komentar harus memberi tahu Anda MENGAPA, mengapa ini MENGAPA kita bicarakan?", Dan saya menjawab pertanyaan itu: MENGAPA yang dibicarakan adalah alasan keberadaan diberikan potongan kode.
Juha Untinen

1
Pertanyaannya secara spesifik menanyakan contoh beberapa kali. Bisakah Anda menambahkan contoh untuk jawaban ini agar lebih bermanfaat?
Bryan Oakley

1
Saya tidak berpikir salah satu dari komentar ini benar-benar bermanfaat. Jika tanda tangan fungsi Anda adalah critters.dance(), maka komentar hanya mengulangi yang sudah jelas, dan "Kami tidak bisa membuatnya bekerja dengan cara lain yang kami coba" sama sekali tidak membantu. Juga, mengatakan "kami akan memanggil metode untuk setiap objek" mengulangi apa yang dikatakan kode dengan sangat jelas.
Pasang kembali Monica

1

Saya belajar SELALU menulis komentar di headerfile C ++ (karena tidak selalu jelas APA fungsinya, walaupun namanya memberi petunjuk yang baik) terutama jika Anda meneruskan API ke pengembang lain atau menggunakan alat untuk autodoc seperti doxygen.

Jadi bagi saya komentar yang khas terlihat seperti

/*** Functionname
/*   What happens here
/*  [in] Params
/*  [out] params
/*** 

Satu-satunya waktu saya menggunakan MENGAPA komentar adalah hal-hal yang sulit untuk dipahami dan kadang-kadang bahkan untuk programmer, seperti "JANGAN SENTUH INI! Karena ..." atau "PROGRAM AKAN MENGHANCURKAN JIKA LINE DIHAPUS ..."

Penanganan masalah, peretasan, dan perilaku aneh memenuhi syarat untuk kriteria MENGAPA di mata saya ...

Contoh yang sangat bagus dan bahkan lucu adalah "solusi" untuk beberapa kode kacau yang ditulis oleh beberapa orang bernama Richard, orang lain membungkusnya dan menjelaskan mengapa dalam komentar ... https://stackoverflow.com/a/184673/979785

Sayangnya ada beberapa kali, di mana Anda dipaksa untuk membungkus bull **** karena Anda tidak dapat menyentuh aslinya, baik karena "selalu seperti itu" atau Anda tidak memiliki akses atau ... yah, Anda tidak punya waktu untuk memperbaiki yang asli untuk tujuan itu tidak benar-benar memenuhi syarat untuk biaya overhead.


7
Kecuali bahwa pertanyaannya adalah tentang komentar , bukan dokumentasi . Mereka sebenarnya hal yang berbeda ( documentationtag ini disesalkan tetapi masih tidak berlaku untuk pertanyaan).
Thomas

Yah maafkan fakta, bahwa dalam komentar bahasa asli saya dan dokumentasi dokumentasi digunakan secara bergantian dan dengan tag saya berasumsi itu berlaku untuk pertanyaan ini juga. Apakah itu benar-benar alasan untuk melakukan downvote?
AnyOneElse

2
Pertanyaan itu beberapa kali menanyakan contoh mengapa komentar, tetapi satu-satunya contoh yang Anda sertakan adalah komentar apa . Orang-orang yang membaca jawaban untuk contoh-contoh mungkin menyesatkan oleh teladan Anda. Bisakah Anda memberikan contoh komentar mengapa ?
Bryan Oakley

walaupun saya mengatakan ada sedikit MENGAPA dalam kode saya, dan saya menyebutkan dua contoh: DIedit ... di sini ada tautan, yang pasti memenuhi syarat untuk MENGAPA
AnyOneElse

@AnyOneElse saya tidak downvote. Itu ada di sana sebelum saya tiba.
Thomas

0

Kode seharusnya menentukan rencana eksekusi. Dengan begitu pengikut program (atau kompiler) dapat mengetahui apa yang harus dilakukan, dan bagaimana melakukannya. Apa yang dipecah menjadi langkah-langkah yang dapat diikuti oleh pengikut program. Langkah-langkah primitif adalah caranya.

Maksud pembuat kode adalah masalah lain. Dalam kode yang sederhana, jelas, dan langsung, maksudnya jelas. Setiap pembaca manusia yang cukup mahir akan sampai pada maksud blok kode, hanya dengan membaca kode. Kebanyakan kode harus dibaca seperti ini.

Kadang-kadang, hubungan antara niat dan rencana tidak jelas. Kode tersebut mengungkapkan apa dan bagaimana, tetapi bukan alasannya. Saat itulah komentar yang mengungkapkan niat itu bermanfaat. Niat programmer adalah alasannya.


3
Pertanyaan itu menanyakan beberapa kali untuk contoh. Bisakah Anda menambahkan contoh pada jawaban Anda agar lebih bermanfaat?
Bryan Oakley

0

Memiliki masalah ini sekarang mengarungi prosedur tersimpan dan pandangan terhadap model data yang kompleks dan agak berbelit-belit.

Kami telah (banyak) membuat pilihan seperti "Kasus ketika x.account bukan nol dan x.menambahkan (pilih alamat dari fedex) kemudian x.account lain y.account end" sepanjang dan produktivitas diharapkan meskipun tidak ada waktu di semua untuk membaca semua kode sumber. Dan contoh semacam ini masuk akal, tapi masih sulit dipahami.

Komentar yang menjelaskan mengapa jika di fedex maka x dan jika tidak maka y - menyoroti seluruh sistem dan ketika kita membaca cukup banyak dari mereka kita mulai mendapatkannya. Dan ini terlalu disederhanakan dan ada ratusan atau ribuan pernyataan serupa. Hatiku bersinar hangat terhadap siapa pun jenis dev dari 2007 adalah yang memasukkan alasan itu.

Jadi ya, model data berbelit-belit yang rumit dan veiws berbulu dan prosedur tersimpan dengan banyak jalur yang valid, mohon karena cinta Gd, beri tahu kami alasannya.


0

Saya baru saja menulis komentar ini; ini adalah contoh nyata menjelaskan mengapa sebaris kode adalah apa itu, dan khususnya mengapa saya mengubahnya.

Metode ini memeriksa data yang disimpan dan menilai apakah itu selesai sampai hari ini di satu sisi, dan melalui tanggal mulai di ujung lainnya.

// In principal, this should be ">=", as we may have data up to the account start
// date but not complete for that day; in practice, 98% of the time if we have
// data for the start date it *is* complete, and requerying it would be a waste
// of time.
while (endDate > accountStartDate)
    ...

Seperti yang mungkin bisa Anda tebak, operator yang lebih besar dari yang ada lebih besar atau sama. Komentar menjelaskan mengapa nilai lama masuk akal dan mengapa nilai baru lebih baik. Jika ada yang melihat ini di masa depan, mereka akan melihat bahwa penggunaan ">" bukan merupakan pengawasan, tetapi suatu optimasi. Mereka kemudian dapat mengubahnya atau meninggalkannya, berdasarkan kebutuhan pada saat itu.

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.