"Saya", "Kami", atau Baik dalam dokumentasi kode


41

Saya menemukan diri saya menulis (semoga) komentar bermanfaat dalam kode (C ++) jenis dokumentasi:

The reason we are doing this is...

Alasan saya menggunakan "kita" daripada "saya" adalah karena saya melakukan banyak penulisan akademis di mana "kita" sering lebih disukai.

Jadi, inilah pertanyaannya. Apakah ada alasan yang baik untuk memilih satu di atas yang lain dalam mendokumentasikan kode:

  1. Gunakan "Kami": Alasan kami melakukan ini adalah ...
  2. Gunakan "Saya": Alasan saya melakukan ini adalah ...
  3. Gunakan nama saya: Alasannya [my name]adalah ...
  4. Suara pasif: Alasan ini dilakukan adalah ...
  5. Baik: Lakukan ini karena ...

Saya memilih # 1 karena saya terbiasa menulis seperti itu, tetapi dokumentasi bukan untuk penulis, itu untuk pembaca, jadi saya bertanya-tanya apakah menambahkan nama pengembang itu membantu atau jika itu hanya menambah satu hal lagi yang perlu diubah saat mempertahankan kode.


Saya pikir itu ke preferensi pribadi. Saya tidak melihat alasan mengapa satu akan lebih jelas daripada yang lain pada umumnya.
ConditionRacer

6
Bagaimana dengan # 5: "Ketika dalam peristiwa manusia ...";)
waxwing

8
"Empat skor dan tujuh detik yang lalu nenek moyang kita mengetahui bahwa foo harus dilarang setidaknya kekuatan kita diatasi dengan NULL"
Philip


2
Kenapa tidak bilang This code was written like this because...? (Suara pasif)
Alvin Wong

Jawaban:


77

Saya akan pergi dengan:

# 6. Deklaratif: ...

Daripada mengatakan "Alasan ini dilakukan adalah karena setiap Foo harus memiliki Bar", katakan saja "Setiap Foo harus memiliki Bar". Buat komentar menjadi pernyataan aktif alasannya, daripada komentar pasif. Ini umumnya gaya penulisan yang lebih baik secara keseluruhan, lebih cocok dengan sifat kode (yang melakukan sesuatu), dan the reason this was donefrasa tidak menambahkan informasi apa pun. Itu juga menghindari persis masalah yang Anda temui.


maukah Anda menjelaskan sedikit tentang mengapa Anda melakukan itu? Tanpa penjelasan, jawaban ini lebih seperti pendapat kosong, agak bertentangan dengan pedoman pendukungnya
gnat

15
@gnat "Alasan ini dilakukan" tidak menambahkan apa pun pada penjelasan. Komentar harus mengandung cukup teks untuk menyampaikan maksud dan tidak lebih. Tinggalkan teks, teks pembuka, dan teks pengisi lainnya.
David Harkness

@gnat - Saya sebenarnya baru saja selesai menambahkan lebih banyak ketika saya melihat komentar Anda.
Bobson

1
Saya pikir contoh saya terlalu sederhana, karena memang "alasan ini dilakukan" tidak menambah apa pun. Tetapi ada beberapa kasus ketika situasi sulit memerlukan penjelasan, dan dalam kasus itu, saya merasa lebih alami untuk menggunakan "kita" atau "saya", seperti saya menggunakan "saya" beberapa kali dalam komentar ini. Tetapi saya pikir jawaban Anda jelas dalam semangat: "deklaratif" menunjukkan: gunakan jumlah kata yang paling sedikit untuk menyampaikan maksudnya dengan jelas.
Alan Turing

7
Saya membaca //seperti becausedalam kebanyakan kasus.
Ilmo Euro

23

Saya lebih suka tidak, dan benar-benar akan meninggalkan frase pengantar sama sekali dan hanya sampai pada intinya. Saya juga mencoba menghindari hanya mengatakan "ini" karena tidak ada cara untuk mengetahui apakah komentar tersebut sinkron dengan kode. Dengan kata lain, alih-alih:

// The reason this was done is to prevent null pointer exceptions later on.

Saya akan mengatakan:

// Frobnicate the widget first so foo can never be null.

Fakta bahwa Anda menambahkan komentar sama sekali menyiratkan Anda menyatakan alasan, jadi Anda tidak perlu memberi tahu orang lain bahwa Anda menjelaskan alasannya secara berlebihan. Buat alasan sespesifik mungkin, sehingga mereka tahu sejelas mungkin bagaimana mempertahankan kode itu nanti.


4

Dalam C # (dan di sebagian besar alat dokumentasi dalam bahasa lain) ada perbedaan antara dokumentasi dan komentar in-line. Pendapat pribadi saya adalah bahwa Anda harus selalu menggunakan komentar formal, gaya deklaratif seperti yang disarankan Bobson dan yang lainnya dalam dokumentasi kelas atau anggota, tetapi di dalam kode, tidak ada yang salah dengan menjadi kurang formal. Bahkan, kadang-kadang komentar informal lebih efektif untuk menjelaskan mengapa sesuatu menjadi don daripada penjelasan lengkap dalam bahasa Inggris formal.

Berikut ini contoh yang saya pikir menggambarkan intinya.

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

4
Catatan: SanitizeDataharus mengembalikan a SafeComplexObject. ;)
Jon Purdy

Saya setuju, tetapi saya lebih suka komentar literal (daripada metaforis), terutama jika mungkin ada pengembang dari latar belakang bahasa yang berbeda.
John B. Lambe

2

Gagasan lain yang perlu dipertimbangkan adalah unit test yang dibuat dengan baik yang menunjukkan mengapa kode bekerja seperti halnya menulis komentar deskriptif. Ini memiliki beberapa manfaat daripada menulis komentar:

  1. Komentar tidak selalu berubah ketika kode diubah yang nantinya dapat menyebabkan kebingungan.

  2. Tes unit memberi pengelola cara mudah untuk bermain dengan kode. Mempelajari basis kode baru bisa jauh lebih mudah jika Anda memiliki unit individual yang dapat Anda hancurkan untuk mengamati perubahan apa.

Meskipun jalan ini membutuhkan lebih banyak pekerjaan di muka, pengujian unit dapat menjadi bentuk dokumentasi yang sangat baik.


1

Komentar yang baik sulit untuk ditulis, dan bahkan komentar terbaik pun seringkali sulit untuk dibaca dan dipahami. Jika komentar Anda cukup ringkas untuk saya serap dan cukup tepat untuk menyampaikan apa yang perlu saya ketahui tentang kode, itu tidak membuat saya berbeda apa kata ganti yang Anda gunakan.

Saya akan benci untuk mencegah seseorang mengomentari kode mereka karena mereka khawatir tentang kasus, tegang, dan orang dari kata ganti mereka.


Izinkan saya mengklarifikasi: untuk komentar yang akan menjadi bagian dari dokumentasi formal, nada yang lebih formal sesuai, dan "Aku" dan "kita" sebaiknya dihindari. Apa yang ada dalam pikiran saya dengan jawaban ini adalah komentar penjelasan sesekali, misalnya ketika Anda telah melakukan sesuatu yang akan terlihat salah untuk pria berikutnya. Dalam kasus-kasus itu, di mana hanya orang yang bekerja di basis kode yang sama yang akan melihatnya, saya katakan lakukan apa pun yang akan menyampaikan maksud Anda dengan sangat jelas, meskipun itu I wrote the code this way because...atau what we really need here is.... Dalam orang-orang kasus, komentar yang jelas lebih penting daripada gaya yang ketat.
John M Gant

1

Alasan saya menggunakan "kita" daripada "saya" adalah karena saya melakukan banyak penulisan akademis di mana "kita" sering lebih disukai.

Ini adalah gaya yang buruk, bahkan untuk makalah akademis, kecuali jika Anda berusaha menyembunyikan siapa yang benar-benar memutuskan hal itu.

Adapun pertanyaan spesifik Anda: Saya tidak akan meninggalkan komentar seperti itu, kecuali jika dimulai dengan:

// TODO: clean this up, ...

atau kecuali itu menjelaskan sesuatu yang sangat penting, yang mungkin tidak begitu jelas dari kode. Dalam hal ini, buat komentar sesingkat mungkin.

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.