Apakah komentar orang pertama mengganggu dan tidak profesional?


63

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?


1
Komentar untuk downvote? Ini adalah pertanyaan Programmers.SE pertama saya, dan saya masih mencoba mencari tahu apa yang membuat pertanyaan P.SE bagus vs pertanyaan SO yang bagus.
dlras2

2
Saya tidak menyuarakan pendapat Anda tetapi saya dapat menebak bahwa mereka tidak menyukai pertanyaan judul karena jawaban atas pertanyaan itu bisa dengan singkat, cerewet, dan terlalu banyak diberikan pada pendapat yang tidak dibantah. Menulis ulang itu agar lebih seperti pertanyaan terakhir Anda mungkin bisa membantu.
DKnight

56
Saya suka 'kita'. Ramah dan inklusif dengan cara yang sehat dan sederhana.
Jeremy

25
Saya pikir saya akan mulai mengomentari semua perbaikan bug yang saya kerjakan sebagai orang ketiga yang mahatahu, harus membuat saya populer di kantor ... "John tidak tahu bahwa penambahannya yang dibuat dengan buruk akan selalu melewati kode ini, membuat pengguna bingung. oleh bidang tampilan yang selalu kosong ... "
DKnight

4
Hanya itu yang bisa saya lakukan untuk memastikan komentar saya tidak salah ketik. Sekarang saya perlu khawatir tentang apakah suara pasif harus digunakan? Selanjutnya saya harus memastikan saya tidak menggantungkan preposisi - saya membayangkan itu adalah sesuatu yang mungkin tidak diterima oleh rekan kerja saya. Dan saya kira saya tidak akan pernah diizinkan untuk menggunakan infinitive split. Fragmen kalimat?
Michael Burr

Jawaban:


103

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


3
+1 sebagai tulisan dengan cara ini mendorong Anda penulis untuk mempertimbangkan pembaca potensial dan yang benar-benar dapat membantu Anda melihat konsep-konsep yang mungkin perlu dijelaskan secara lebih baik.
Justin Ohms

64
// we approve of this answer:)
Jarrod Dixon

3
+1 dan sebuah amplifikasi: sebaliknya, konstruksi pasif-suara seperti "dapat diubah ukurannya" ditolak secara tertulis karena kami merasa sulit untuk dipahami. Jika Anda menggunakan suara pasif, Anda memaksa pembaca untuk menemukan dan mengingat subjek untuk kalimat tersebut.
msw

1
@ msw: bukankah seharusnya 'kami menolak konstruksi suara pasif seperti "itu bisa diubah ukurannya" ...' kalau begitu?
tdammers

2
@ msw, dalam bahasa Rusia, misalnya, konstruksi suara pasif lebih umum dan dipahami lebih mudah karena beberapa perbedaan budaya. (Dan tidak, aku tidak menulis kalimat di pasif pada tujuan!)
P Shved

22

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.

4
"Jika pesan dapat disampaikan dengan cara yang tidak terlalu jelas, mengapa memilih yang lain?" Sebagai seseorang yang harus membenturkan kepalanya ke dinding mencoba mengimplementasikan perpustakaan seseorang yang tidak terdokumentasi dengan baik - open source libs terkenal karena hal ini - saya katakan saya lebih suka memiliki terlalu banyak komentar daripada terlalu sedikit. Saya pikir saya setuju dengan Anda di olah jika Anda maksud menggunakan kalimat yang baik dengan tanda baca yang benar yang masuk akal.
Jonathan Henson

3
+1 karena tidak memikul semua tanggung jawab dalam pengaturan tim. Dan sementara saya setuju untuk mencoba menghindari komentar verbal, kadang-kadang kalimat pasif bisa lebih sulit untuk dibaca (seperti yang ditunjukkan oleh jkj) dan tidak kurang verbose, dan saya lebih suka menghindari kebingungan. =]
dlras2

2
@ Jonathan Henson: Banyak komentar baik, tetapi hanya jika mereka berisi banyak informasi berguna. Jika jumlah informasi yang sama dapat diungkapkan dalam dua cara yang setara, yang lebih pendek lebih baik.
tammers

Saran saya adalah untuk menghindari penggunaan suara pasif. Ini lebih sulit untuk dipahami, terutama untuk penutur bahasa Inggris non-asli.
Ville Laurikari

18

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


Ini persis gayaku juga. Kedua cara yang Anda gambarkan memiliki tempatnya.
zourtney

9
Yang terakhir memiliki "kita" di dalamnya juga. Saya merasa menarik bahwa orang secara alami menulis komentar dalam bentuk jamak orang pertama.
Reid

@ Reid wow ya itu hanya naluri, saya bahkan tidak menyadarinya. Tapi itu bisa saja dengan mudah mengatakan "itu".
Tesserex

8

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.


3
Saya pribadi tidak merasa bahwa "satu" sudah ketinggalan jaman. Ya, ini jarang digunakan, karena itu bukan sesuatu yang digunakan seseorang dari waktu ke waktu. Namun, ada sedikit kemungkinan untuk nol bahwa menggunakan "satu" dalam arti komentar akan tidak dapat dibaca atau sebaliknya mengurangi kegunaan.
Billy ONeal

7

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)


3
+1 karena lebih suka imperatif, saya belum memikirkan itu. Juga, ya, saya seharusnya tidak menggunakan yang telanjang 1. Saya biasanya cukup baik tentang itu ... Serahkan pada saya untuk mengirim salah satu dari beberapa kali itu terlintas di benak saya di internet.
dlras2

6

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


Saya rasa secara linguistik ini tidak benar. Yang pertama adalah keharusan, tidak memiliki subjek. "Tolong tutup pintunya." Meskipun kira-kira artinya sama dengan "tolong, bisakah Anda menutup pintu?" itu adalah bentuk tata bahasa yang berbeda, bukan singkatan. Dalam contoh kedua, Anda bisa saja mengatakan "(Telah) menangkap pengecualian. (Ini akan) menunjukkan dialog kesalahan."
Inca

3

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.


2
Peringatan Dijkstra! Kalau saja lebih banyak hal punya satu :(
Tom Anderson

Saya tidak berpikir menulis komentar dalam bentuk jamak orang pertama adalah antropomorfisme. Saya pikir itu menyiratkan, "Sekarang kita menginstruksikan komputer untuk ...", seolah-olah programmer menulis komentar memimpin pembaca melalui kode-kodenya.
blujay

2

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.


Gagasan menarik; bagaimana orang akan mengungkapkan gagasan "X harus setidaknya 5" atau "Y harus tidak lebih dari 23"?
supercat

@supercat - "Nilai X harus memiliki besaran 5 atau lebih besar". "Nilai Y tidak boleh melebihi 23". Kesetaraan, logis atau aritmatika, tidak boleh menggunakan kata kerja "menjadi". "X harus mengandung 5", atau "X mengevaluasi hingga 5" atau "X memiliki nilai 5" atau semacamnya. Jika Anda menemukan komentar yang sangat tidak jelas, cari kata kerja "menjadi". Saya bertaruh bahwa komentar yang tidak jelas menggunakan noting tetapi "to be". Perhatikan juga bahwa saya menulis jawaban di atas dalam E-Prime.
Bruce Ediger

Yang kedua baik-baik saja; yang pertama tidak begitu banyak, karena -6 memiliki besaran 5 atau lebih besar.
supercat

@ supercat - sangat baik. "X harus memiliki nilai integer yang ditandatangani 5 atau lebih besar". Di AS, kami akan menyebut "besaran" Anda "nilai absolut", yang memperkuat poin saya untuk menggambarkan nilai variabel, bukan variabel sebagai nilai, yang muncul dari persamaan kesetaraan.
Bruce Ediger

2

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.


11
-1 karena: tidak ada cara yang benar, saya menemukan ringkasan saya / Anda / Kami sedikit keluar dari kontak dan saya tidak mengerti bagian terakhir. Selain itu: Ketika saya mengatakan "kami" dalam komentar saya, saya tidak mencoba berbicara seperti raja - saya berbicara dengan Anda, orang itu membaca kode saya, dan menuntun Anda melewati pikiran saya berdampingan.
doppelgreener

2

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.


+1 untuk Doxygen dan JavaDoc. Saya setuju bahwa dokumentasi berbeda dari komentar, (meskipun beberapa komentar menghasilkan dokumentasi,) dan saya melakukan yang terbaik untuk menjaga dokumentasi tersebut selangkah lebih formal daripada komentar saya.
dlras2

1

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 :)


1

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 :-)


0

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.


Bahasa Inggris pasif jarang kedengarannya bagus: "session_id dapat diperoleh dari SYSSession.getSessionID () jika diperlukan"
jkj

0

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.

1
Maaf, tapi saya bukan penggemar gaya ini sama sekali. Terutama karena kode ini digunakan sekali, di satu tempat, dan itu sudah satu-satunya dalam metode mengubah ukuran. Saya lebih suka komentar singkat yang ditulis dengan baik untuk menambah kompleksitas melalui refactoring, terutama ketika bekerja dengan VB6 debugger. Sebagai tambahan, CanThisFormBeResizedmungkin harus ThisFormCanBeResizedjika itu akan digunakan seperti If ThisFormCanBeResized Then.
dlras2

1
Preferensi itu. Saya menggunakan metode boolean pribadi seperti function() { return this.windowState != 1 }komentar apa pun. +1 dari saya
keppla

1
@Dan, bagaimana jika orang lain datang kemudian: mengapa membuat mereka mencari dan mencari tahu kembali logika untuk menentukan apakah sebuah jendela dapat diminimalkan? Mereka bahkan mungkin tidak melihat garis kecil kode Anda dengan komentar dan menambahkan sendiri. Sekarang Anda punya 2 tempat yang perlu diubah jika logikanya berubah dan 2 tempat di mana komentar bisa menjadi tidak sinkron dengan kode. Mengapa metode 1 baris yang disebut dengan baik (yang tidak mengubah keadaan) menambah kompleksitas? Ini yang paling sederhana dan salah satu refactor terbersih yang ada.
Steve Dunn

0

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.


0

Secara pribadi saya akan menulis (dalam C #):

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

Atau sesuatu seperti itu, sehingga tidak membutuhkan komentar.


ResizeWindowSafelyakan menyiratkan itu dapat dipanggil jika Anda tidak tahu apakah akan mengubah ukuran atau tidak, dan dengan demikian perlu memasukkan if (WindowState != WindowState.Minimised)dirinya sendiri.
dlras2
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.