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

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

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.

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

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.

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.

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.