Untuk komentar kontrol versi apa yang dilakukan / direkomendasikan pengguna lain - lampau atau sekarang?

Yaitu

• Diubah x menjadi y.
• atau
• Mengubah x menjadi y.

Komentar harus dibaca dalam konteks, jadi:

Menyajikan

Untuk komentar sumber di atas metode, atau sebelum beberapa perilaku terjadi:

// This function does X
function doX() { ... }

Lalu

Untuk komentar sumber setelah beberapa perilaku terjadi

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

Dan untuk pesan komit

fungsi X berubah

Contoh campuran:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}

Masa Lalu - Karena siapa pun yang membacanya di masa depan akan merujuk pada tindakan perubahan seperti yang terjadi di masa lalu.

Menulis sesuatu seperti "Mengubah" menyiratkan bahwa Anda sedang dalam proses membuat perubahan dan bahwa kode mungkin tidak selesai.

catatan: Secara pribadi, saya hanya memasukkan komentar perubahan ketika perubahan drastis telah terjadi.

Komentar adalah hal-hal yang statis, sehingga mereka harus menyajikan keadaan program apa adanya , dan tidak seperti yang akan terjadi. Untuk menjawab pertanyaan spesifik Anda, akan lebih tepat menggunakan past tense .

Namun, jenis komentar ini lebih cocok untuk sistem kontrol versi Anda. Kontrol versi melakukan pekerjaan pelacakan perubahan yang jauh lebih baik daripada komentar manual. Dengan sistem kontrol Versi, lebih tepat untuk mendokumentasikan dalam present tense karena komentar-komentar tersebut berlaku pada saat perubahan dilakukan. Namun, keduanya akan berhasil.

Saya akan sangat menyarankan bahwa satu-satunya komentar dalam kode Anda haruslah yang diperlukan untuk memahami kode itu sendiri - tujuan, logika bisnis, dan kasus luar biasa. Tinggalkan perubahan atur dokumentasi ke sistem kontrol versi Anda. Jika Anda tidak menggunakan VCS, mulailah sekarang. Ada beberapa VCS berkualitas tinggi yang gratis (Subversi, Mercurial, Git, dll.).

Saya menggunakan present present tense, jadi sesuatu seperti:

Ubah "x" menjadi "y"

Ini direkomendasikan oleh pengembang Git:

• tubuh harus memberikan pesan komit yang bermakna, yang:
  • menggunakan imperatif, present tense: "perubahan", bukan "diubah" atau "perubahan".

Pada awalnya mungkin terlihat agak aneh, tetapi jika Anda menganggap komit sebagai tambalan yang melakukan sesuatu, itu lebih masuk akal. (Ini terutama berlaku dalam DVCS seperti Git, di mana Anda menarik perubahan dari orang lain yang bertindak atas repo Anda.)

Itu tidak masalah; Saya pikir ini gaya dan preferensi pribadi. Seperti menulis hampir semua hal, konsistenlah dengan diri Anda dan dengan komentar lain.

Komentar kode harus alami untuk dibaca.

Jika Anda membaca kode yang mengatakan pada diri sendiri "Kode ini sedang melakukan X" maka Anda harus menulis komentar dalam present tense karena ini kemungkinan orang yang membaca kode pada saat itu akan berpikir juga. Jika di sisi lain Anda berpikir pada titik tertentu "Kode ini melakukan X" maka itu harus lampau. Pada akhirnya itu tergantung pada preferensi pribadi kecuali karena alasan tertentu Anda di bawah pedoman tentang bagaimana mengomentari kode Anda (yaitu untuk proyek tim atau untuk kelas, dll).

Jika Anda menggunakan git, konvensi ini menggunakan present tense karena komit pesan yang dihasilkan dengan alat git (misal gabung) gunakan present tense.

Anda harus menggunakan bentuk lampau.

Alasannya karena Anda menjawab pertanyaan apa yang dilakukan komitmen ini? Anggap saja mengatakan pada VCS Anda tentang apa yang Anda lakukan:

Komit 123
Mengubah XYZ untuk melakukan ABC

Untuk memberikan contoh balasan, menggunakan future tense membuatnya terdengar seperti Anda meminta orang lain untuk melakukannya:

Komit 123
Ubah XYZ untuk melakukan ABC

dan menggunakan present tense terdengar seperti Anda setengah jalan:

Komit 123
Mengubah XYZ untuk melakukan ABC

Gunakan present tense: "Ubah X ke Y," hampir seolah-olah itu adalah item pada daftar TODO yang jelas.

Secara umum, seperti halnya skenario, hindari kata kerja seperti "menjadi" dan "apa adanya". Misalnya, itu bukan "dia berjalan," tetapi "dia berjalan."

Tetapi dalam contoh khusus ini - jika Anda berbicara tentang komentar kode, dan bukan komentar check-in - saya percaya "Ubah X ke Y" adalah komentar yang mengerikan. Itu tidak menambahkan informasi baru, dan jika kode itu berubah mungkin bahkan salah. Lebih baik jika Anda mengekstrak kode ke metode (atau kelas) dan kemudian mendokumentasikan metode itu. Jika cukup jelas maka hanya nama metode yang bagus akan cukup.

Omong-omong, untuk mendokumentasikan metode, Anda dapat menggunakan bentuk waktu mendatang, misalnya: "Jika angka yang diberikan negatif, absakan mengembalikan besarnya angka."

Komentar adalah (atau seharusnya), seperti apa pun yang ditulis, ekspresi sesuatu, dan mereka harus mengikuti aturan yang sama dalam bahasa alami (dengan mempertimbangkan singkatan dan singkatan khusus untuk situasi atau artefak yang didokumentasikan.

Komentar pada present tense ( .ie "itu berubah" atau "itu berubah" ) menunjukkan bahwa sepotong data yang dioperasikan oleh algoritma yang didokumentasikan sedang dipengaruhi. Artinya, ini menunjukkan apa yang dilakukan kode atau apa yang terjadi pada data yang dimanipulasi.

Komentar dalam bentuk lampau harus menunjukkan penegasan, prasyarat atau kondisi setelah sesuatu yang telah terjadi sebelum titik di mana komentar berada. Sebagai contoh:

Input sudah divalidasi sebelum memasukkan blok kode ini

atau

Data telah ditulis ke file pada akhir kode ini dieksekusi

Komentar dalam bentuk lampau juga dapat menjelaskan mengapa sesuatu dilakukan ( fungsi ini tidak X dan Y untuk menangani masalah dengan database warisan. )

Komentar dalam bentuk lampau yang mengindikasikan perubahan pada kode itu sendiri (.ie. X diubah menjadi Y ) tidak boleh ada dalam kode. Mereka seharusnya ada sebagai revisi komentar dalam repositori kode sumber.

Komentar di masa depan harus menunjukkan kondisi yang perlu dipenuhi atau ditangani, tetapi untuk X atau Y alasan tidak dilakukan saat ini. Sebagai contoh:

Ketika kami akhirnya memigrasi db, kami harus mengubah logika ini

atau

TODO: secepatnya, kembali validasi input - mungkin gagal untuk tipe input X atau Y, mungkin memerlukan perubahan besar yang tidak dapat diimplementasikan sekarang.

Untuk jenis komentar TODO nanti , beberapa bentuk dokumentasi lain harus ada untuk memastikan bahwa perubahan tersebut benar-benar terjadi. Hal terakhir yang Anda inginkan adalah TODO hilang dalam ruang dan waktu: P

Ambillah dengan sebutir garam, tetapi biasanya itu adalah aturan yang biasanya saya ikuti ketika saya melakukan komentar saya sendiri.

Mengomentari adalah tentang berkomunikasi dengan manusia, jadi walaupun konsistensi itu penting, penting untuk tidak terjebak dalam prinsip ketika prinsip itu sendiri menghalangi komunikasi yang baik. Yang mengatakan, saya menggunakan pseudo-standar berikut:

• Komentar yang menggambarkan perilaku yang diinginkan berbentuk kalimat imperatif present-tense.

  // Calculate the width of the curve at x height.
  

• Gunakan serangkaian kata kunci lengkap untuk menjelaskan tema umum dalam pengkodean (dan untuk membuatnya mudah dicari):

  // NOTE: <This code was written this way for a reason.>
  // TODO: <This code is incomplete. Finish it.>
  // HACK: <This code was written this way for a reason that you won't like.>
  // FIXME: <This code has a known flaw. Fix it.>