Apakah komentar orang pertama mengganggu dan tidak profesional?

Saya baru saja menemukan diri saya menulis komentar berikut dalam beberapa kode (kuno Visual Basic 6.0) yang saya tulis:

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

Saya tidak yakin mengapa saya secara tidak sadar menggunakan "kami" dalam komentar saya. Saya curiga itu karena saya membayangkan seseorang melangkah melalui kode, seolah-olah mereka benar-benar "melakukan" semua perintah pada setiap baris, daripada hanya menontonnya terjadi. Dengan pola pikir ini, saya bisa menggunakan I can resize it, karena saya yang "melakukannya" saat ini, atau you can resize it, seolah-olah saya berbicara kepada siapa pun yang "melakukannya" di masa depan, tetapi karena kedua kasus ini kemungkinan besar akan terjadi, saya menggunakan "kami" seolah-olah saya memimpin orang lain melalui kode saya.

Saya hanya dapat menulis ulang it can be resizeddan menghindari masalah, tetapi memicu rasa ingin tahu saya: apakah biasa menggunakan orang pertama seperti ini dalam komentar, atau dianggap mengganggu dan / atau tidak profesional?

Komentar harus ditulis untuk dipahami manusia. Ketika manusia berkomunikasi, kita biasanya menggunakan "Aku", "Kita", "Kamu", dll.

Ketika seseorang mencoba memahami beberapa kode, ada dua atau lebih aktor: orang yang membacanya, dan penulis asli kode tersebut. Mengatakan "kita" tidak apa-apa. Kecuali dengan 'profesional', maksud Anda 'seperti robot'.

Saya menyarankan untuk menjauh dari menggunakan 'saya' karena secara otomatis mengasumsikan semua tanggung jawab untuk kode. Jika orang lain membacanya, itu akan terlihat buruk karena itu dimaksudkan sebagai upaya tim dalam kasus ini. Saya acuh tak acuh tentang menggunakan 'kita'. Namun, hal itu mungkin muncul sebagai termasuk pembaca lain dengan tidak hormat.

Suara saya masih berlaku untuk singkat dan singkat. Jika pesan dapat disampaikan dengan cara yang tidak terlalu jelas, mengapa memilih yang lain? Jadi, mengenai contoh ini, saya akan menulis:

'The form is not minimized so it can be resized safely.

Saya mengambil satu dari dua pendekatan, biasanya apa pun yang terdengar lebih baik.

Dalam menjelaskan hal-hal seperti persyaratan atau pembenaran, saya menggunakan "kami" seperti yang Anda miliki di sana:

// We can't proceed unless the user has given us this information.

Jika saya menjelaskan prosesnya, saya cenderung menggunakan suara perintah (perintah) (koreksi saya jika itu istilah yang salah):

// Get the foo from bar and make sure it follows our required format.

Yang terakhir bisa nyaris mengulangi kode, tetapi ada kegunaannya. Jadi itu tidak menggunakan saya atau kita, tetapi sebenarnya itu menyiratkan "Anda".

Saya pikir itu hanya variasi pada gaya penulisan akademik / teknis, yang sering bersifat pribadi. Menggunakan suara pasif, menggunakan "kerajaan kita" ("satu" sangat kuno).

Sebagai aturan umum, itu adalah non-spesifik yang akan menggunakannya pula - komentar adalah untuk pengelola menguntungkan, biasanya tidak hanya untuk penulis asli.

Yang mengatakan, saya sering menggunakan orang pertama dalam komentar - untuk menjelaskan mengapa saya membuat keputusan tertentu, dan apa yang saya pikirkan.

Komentar harus memberi tahu Anda mengapa sesuatu dilakukan, bukan apa yang dilakukan. Jika apa yang dilakukan tidak jelas dari kode, perbaiki kode, jangan hanya menambahkan komentar. Orang pertama, orang kedua, dll. Tidak masalah, yang penting adalah mengkomunikasikan informasi yang diperlukan.

Jika Anda harus menceritakan kodenya, pilih imperatif, mis

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

(Dan tolong jangan gunakan konstanta kosong seperti "1" dalam kode)

Mungkin kita mengacu pada orang-orang kecil di dalam program yang membuat keajaiban terjadi? :)

Suara pasif bahasa Inggris sulit digunakan dan terdengar buruk. Orang-orang suka menggunakan formulir orang (saya, Anda, kami, satu).

Contoh:

(Anda / kita / seseorang harus) menggunakan delegasi untuk menyampaikan peristiwa mengubah ukuran jendela ke orang tua

Seorang delegasi harus digunakan untuk melewati peristiwa mengubah ukuran jendela ke orang tua

Contoh lain (perhatikan bahwa Anda sering dapat menghilangkan formulir orang dalam komentar):

(Kami) menangkap pengecualian. (Kami akan) menampilkan dialog kesalahan.

Pengecualian ditangkap dan dialog kesalahan akan ditampilkan.

PS. Mengganti pasif dengan "Anda" sangat umum dalam bahasa Inggris sehingga sudah mulai bocor ke bahasa lain juga. Kedengarannya sangat lucu, misalnya, bahasa Finlandia di mana bentuk tunggal orang kedua ada (seperti bahasa Inggris "Engkau").

Jika Anda berbicara tentang pelaksanaan program, itu bukan 'kami', 'Anda' atau 'Saya'. Antropomorfisme mungkin tersebar luas hingga tidak terlalu mencolok tetapi ini kebiasaan yang berbahaya (PDF Warning. Dijkstra Warning.):

Saya pikir antropomorfisme adalah yang terburuk dari semua. Saya sekarang telah melihat program "mencoba melakukan sesuatu", "ingin melakukan sesuatu", "percaya hal-hal itu benar", "mengetahui hal-hal" dll. Jangan begitu naif untuk percaya bahwa penggunaan bahasa ini tidak berbahaya. Itu mengundang programmer untuk mengidentifikasi dirinya dengan pelaksanaan program dan hampir memaksanya penggunaan semantik operasional.

Saya tidak berpikir orang pertama atau "kerajaan kita" tampaknya tidak profesional, atau mengganggu. Saya benar-benar berpikir bahwa kita harus berusaha untuk menulis komentar berbahasa Inggris di E-Prime , bagian dari bahasa Inggris yang tidak memiliki kata kerja "menjadi".

Jika Anda menggunakan "menjadi" secara berlebihan dalam komentar, Anda akan mendapatkan pernyataan yang membingungkan seperti:

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

Yah, mungkin tidak semuanya sekaligus, tetapi is-of-equality benar-benar dapat membuat komentar tidak jelas.

Saya pikir persyaratan menulis di E-Prime membantu memperjelas persyaratan itu, karena penulis harus menunjukkan aktor beserta tindakannya.

Gaya yang benar untuk berkomentar adalah orang ketiga impersonal; " Bentuknya tidak diminimalisir, sehingga bisa diubah ukurannya dengan aman ".

• Saya naif.
• Anda kasar.
• Kami terlalu formal (dan kerajaan).

Setiap kalimat dapat diulang dengan cara ini (lihat di atas) dan itu adalah satu-satunya cara profesional untuk menulis.

Itu tergantung pada komentar.

Biasanya, saya menulis komentar dengan cara yang disarankan oleh The Mouth of a Cow . Saya juga selalu menulis komentar yang menghasilkan dokumentasi (Doxygen, JavaDoc) dengan cara ini.

Namun, banyak yang sering mengabaikan penggunaan kontrol versi untuk mengidentifikasi siapa yang menulis / menyentuh baris dalam file sumber. Ada saat-saat mengatakan "Aku" sesuai, terutama ketika itu cukup mudah untuk melacak "Aku" kembali ke orang yang menulis kode. Jika Anda, sebagai individu, membuat keputusan, saya sarankan menggunakan "I" (bersama dengan kontrol versi) untuk mengidentifikasi dan melacak keputusan yang sesuai dengan kode.

Ayah tua saya yang baik (mhrip) akan bertanya: "Apakah kamu tidak memiliki hal-hal yang lebih penting untuk diganggu?"

Namun, secara pribadi, saya suka "kita". Dan saya juga bertanya-tanya mengapa saya menulis kami di dokumen up-stream, bahkan tidak kode, mengingat saya satu-satunya karyawan di perusahaan saya.

Namun, saya sendiri dan saya setuju bahwa dengan cara ini kita merasa tidak begitu kesepian :)

Apakah saya satu-satunya yang menulis "kami" dan berpikir "saya dan komputer" (atau "tim saya dan komputer")? "Kami" akan menangani permintaan yang diberikan pihak luar kepada kami, itu berarti "kami" perlu membaca permintaan, membuka beberapa jendela, melakukan beberapa perhitungan, berdasarkan persyaratan bisnis "kami". Ini juga membantu untuk melihat kode sebagai bagian dari sisi Anda, bukan musuh :-)

Untuk komentar singkat, kadang-kadang saya menulis sebagai orang kedua, seolah-olah saya sedang menginstruksikan orang lain, hampir seperti pesan yang diarahkan ke pengembang berikutnya untuk membaca komentar. Seperti

//You can get a session_id from SYSSession.getSessionID() if you need one

Komentar yang lebih panjang (seperti header fungsi yang panjang atau beberapa baris deskripsi algoritma) Saya mencoba untuk menjaga netral, tidak ada orang pertama, orang kedua, atau orang ketiga.

Anda menambahkan komentar ini karena kode tidak cukup jelas. Saya biasanya menemukan maksud mengekspresikan melalui metode yang didefinisikan dengan baik menghindari penggunaan komentar. Sebagai contoh, garis bisa bisa dipindahkan ke metode bernama CanThisFormBeResized.

Metode yang bernama baik, betapapun kecilnya, mengalahkan komentar, karena mudah bagi komentar dan kode menjadi tidak sinkron.

Jadi, jika sebagian besar komentar dapat diekspresikan dalam kode, itu menyisakan sangat sedikit alasan untuk komentar

• Jika komentar Anda adalah pendapat Anda, maka mulailah dengan "Saya"
• Jika menurut Anda komentar Anda harus merupakan pendapat bersama (mis. Praktik terbaik), maka mulailah dengan "kami"
• Jika komentar Anda diarahkan pada beberapa kode cerdik yang ditulis oleh setengah akal, maka memo komentar dan berjalan dan meninju mereka kode membingungkan dari seorang rekan, maka alamat ini tatap muka dengan mereka.

Sebagai aturan praktis saya sarankan menggunakan orang pertama, yaitu I,.

Mengapa? Bukan karena sifat posesif saya, tetapi karena ketika orang berbicara dalam perspektif lain, mereka cenderung menggunakan terlalu banyak kata atau membuat kalimat terlalu rumit, dan tersesat dalam mencoba menjelaskan sesuatu. Orang pertama cenderung selalu yang paling mudah dibaca.

Secara pribadi saya akan menulis (dalam C #):

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

Atau sesuatu seperti itu, sehingga tidak membutuhkan komentar.