Bagaimana saya bisa meminta atasan saya (dengan cara sopan) untuk mengomentari kodenya?


72

Saya diajari oleh bos saya (saya baru saja selesai sekolah dan dia menginginkan seseorang dengan sedikit pengalaman pemrograman, jadi dia memilih saya untuk melatih saya tentang apa yang menjadi spesialisasi perusahaan itu) dan mulai bekerja dengan aplikasi ASP.NET MVC , beberapa HTML dan CSS . Saya baik-baik saja dengan hal-hal desain web yang dia berikan kepada saya (cukup mudah dimengerti tanpa klarifikasi).

Tapi misalnya, dia memberi saya tugas untuk dilakukan dengan ASP.NET MVC, dia menjelaskannya dengan sangat baik. Tetapi dia tidak menjelaskan apa pun dalam kode yang baru saja dia berikan kepada saya. (Kami menggunakan kontrol sumber dalam Visual Studio 2013 ), jadi ini benar-benar ratusan baris kode, tanpa latar belakang tentang apa yang seharusnya dilakukan. Jenis kode yang saya lihat adalah kode yang belum pernah saya lihat sebelumnya, jadi sangat sulit untuk mencoba dan mencari tahu.

Saya akan mencoba dan mengajukan lebih banyak pertanyaan kepadanya, tetapi dia selalu bekerja (ini urusannya sendiri), dan saya merasa seolah-olah dia mungkin merasa terganggu dengan semua pertanyaan yang saya miliki ini.

Jadi hanya sesuatu yang akan membantu saya sampai saya bisa menguasai beberapa hal, bagaimana saya bisa meminta atasan saya untuk memberikan komentar ke dalam kode yang dia berikan kepada saya, tetapi dengan sopan?


2
Komentar bukan untuk diskusi panjang; percakapan ini telah dipindahkan ke obrolan .
maple_shaft

1
Alternatif untuk bertanya adalah dengan menggunakan pengindeksan kode sumber dan alat navigasi seperti SourceGraph .
Dan Dascalescu

Saya baru-baru ini mulai dalam sebuah tim yang mengerjakan aplikasi MVC5 (> 100k lines) besar. Ada 150 unit tes untuk semuanya dan semuanya ditambahkan oleh saya selama beberapa bulan terakhir. Beberapa komentar dalam kode sebagian besar dalam bahasa lain. Welcome to business programming :)
Mark K Cowan

Pertanyaan seperti "Bagaimana saya meminta X untuk melakukan Y" biasanya lebih baik di Tempat Kerja ketika X melibatkan kolega.
Blrfl

Jawaban:


130

Anda berada di 'ujung dalam' dan, menurut saya, itulah cara terbaik untuk belajar. Bukan karena Anda melihat hal-hal yang tidak Anda ketahui, tetapi karena hal itu memaksa Anda untuk menjadi lebih banyak akal dan mencari tahu komponen apa yang memainkan peran apa dalam sistem yang Anda baru kenal.

Itu tidak membantu bahwa bos Anda terlalu sibuk untuk menangani seseorang yang ingin tahu (dan Anda sepenuhnya berhak untuk ingin tahu; Anda ingin belajar, yang baik). Tetapi, sayangnya, meminta senior Anda untuk mengubah gaya dan pendekatan mereka demi pembelajaran Anda mungkin tidak turun terlalu baik, terutama karena Anda sedang berurusan dengan seseorang yang Anda katakan sedang sibuk.

Duduk di depan ribuan baris kode yang tidak Anda kenal adalah norma. Anda tidak dapat selalu menjelaskannya hitam putih dengan komentar. Namun demi belajar saat Anda masih baru, jika Anda merasa Anda harus meminta komentar kepadanya - mungkin jelaskan alasannya. Jelaskan itu karena Anda tidak ingin mengganggunya dengan pertanyaan karena dia sering sibuk. Hal ini tidak hanya akan terlihat kurang seperti Anda menyuruhnya melakukan sesuatu, tetapi juga membuka peluang untuk berdiskusi tentang bagaimana dia mungkin, sebaliknya, lebih memilih untuk mengesampingkan pertanyaan dengan meminta waktu.


185
+1 untuk "Duduk di depan ribuan baris kode yang tidak Anda kenal adalah norma" - ini tidak pernah muncul dalam kursus pemrograman dan selalu muncul di pekerjaan.
pjc50

11
Terima kasih telah memberi saya harapan, saya sebenarnya berpikir untuk berhenti dari pekerjaan dan pergi ke universitas atau sesuatu. Saya berbicara dengannya beberapa saat yang lalu dan dia berkata dia sangat terkesan dengan kemajuan saya bla bla .. @ pjc50 Saya sangat setuju dengan Anda pada dasarnya mengikuti tes dan pelajaran setelahnya. Ive mungkin tidak belajar lebih banyak di bulan lalu daripada 3 tahun di sekolah!
Aidan Quinn

9
Persis. Programming-as-a-trade secara efektif membutuhkan magang (mungkin otodidak), sementara kursus CS mungkin mengandung sangat sedikit pemrograman aktual. Mereka simbiotik tetapi bukan hal yang sama. Anda tidak harus pergi ke universitas untuk menjadi programmer yang hebat, tetapi itu membuatnya jauh lebih mudah untuk diterima, bahkan jika kursus memiliki sedikit relevansi dengan pekerjaan yang Anda lamar.
pjc50

11
@AidanQuinn, Sindrom Impostor ( en.wikipedia.org/wiki/Impostor_syndrome ) dapat bekerja keras di awal pekerjaan baru dan terlebih lagi di awal pekerjaan pertama Anda. Jika dia mengatakan Anda baik-baik saja, bawalah dia mendengar kata-katanya.
Celos

6
Pemrograman sebagian besar waktu merasa tidak kompeten dengan ledakan singkat perasaan jenius seperti dewa.
MrDosu

75

Pertama, merangkak melalui ribuan baris kode asing dan merasa hilang adalah bagaimana setiap proyek perangkat lunak, di mana saja, dari awal waktu.

Perbedaan terbesar antara Anda dan seorang programmer berpengalaman adalah bahwa Anda tidak terbiasa dengannya.


Beberapa hal yang perlu diingat:

  1. Dengan upaya yang cukup, setiap bit kode dapat dimengerti. Banyak orang merasa frustrasi jika mereka tidak dapat menemukan sesuatu dalam beberapa menit. Lebih sabar dari itu.

  2. Seorang bos yang baik adalah seterbuka mungkin untuk gangguan dan pertanyaan. Karyawan yang baik berusaha sekeras mungkin untuk meminimalkan gangguan dan pertanyaan. Sadarilah itu.

  3. Gangguan lebih mahal daripada pertanyaan. Anda dapat memanfaatkan waktu dan bos Anda dengan lebih baik dengan mengkonsolidasikan diskusi Anda, dan dengan tidak pernah mengakhiri percakapan dengan perasaan bingung.

  4. Bos Anda adalah programmer yang lebih baik dari Anda. (Mungkin.) Itu bukan untuk mengatakan bahwa Anda tidak bisa lebih kuat di beberapa bidang, tetapi secara keseluruhan keahliannya lebih besar. Sampai Anda memiliki banyak pengalaman, pastikan Anda belajar dari keahliannya sebanyak yang Anda bisa.

  5. Jika Anda yakin bahwa lebih banyak komentar akan membantu kode secara signifikan, tanyakan kepada bos Anda. "Sulit bagiku untuk memahami apa yang sedang terjadi di beberapa tempat. Ketika aku memikirkannya, apakah kamu keberatan jika aku menambahkan komentar?" Mungkin dia benci komentar. Mungkin dia akan menyukainya. Mungkin dia akan acuh tak acuh.

Pada akhirnya, bagaimanapun, ada kemungkinan bahwa beberapa bulan dari sekarang Anda akan ingat menanyakan hal ini dan berpikir, "Hah, saya bertanya-tanya dengan apa saya bermasalah? Ini tidak terlalu buruk. Hm, yah, tidak masalah."


6
Saya terutama menyukai poin 3. Kadang-kadang bermanfaat untuk menulis email dua baris cepat memintanya untuk datang memberi Anda bantuan dengan masalah bahkan jika dia hanya duduk di kantor beberapa kaki jauhnya dari Anda. Itu memungkinkan dia menentukan kapan dia siap untuk diinterupsi, dan memberi Anda lebih banyak waktu untuk menyusun daftar pertanyaan yang lebih lengkap sebelum diskusi benar-benar terjadi.
Phil

1
juga untuk @Phil. Anda akan kagum pada berapa banyak pertanyaan yang Anda temukan jawabannya sendiri, hanya dengan hati-hati menyusun pertanyaan yang jelas dalam email. Hanya proses menjelaskan kebingungan Anda dengan presisi dapat menyalakan lampu. Tidak dapat memberi tahu Anda berapa kali saya menulis surel semacam itu yang tidak pernah dikirim karena saya sudah menemukannya.
kmote

3
@kmote, saya punya banyak pertanyaan Stack Overflow yang belum ditanyakan yang terjadi dengan cara yang sama :)
Paul Draper

18

Jika bos Anda tidak punya waktu untuk menjawab semua pertanyaan Anda, mengapa menurut Anda dia akan punya waktu untuk mengomentari kode warisannya? Dan terlebih lagi, apa yang membuat Anda berpikir komentarnya akan benar-benar menggambarkan potongan-potongan yang Anda tidak mengerti untuk saat ini? Menurut pengalaman saya, mencoba mengubah gaya pemrograman bos Anda hanya dengan memintanya tidak akan berhasil, sopan atau tidak.

Hal terbaik yang dapat Anda lakukan dalam situasi seperti ini: komentari bagian-bagian kode yang perlu Anda pahami untuk melakukan pekerjaan Anda sendiri - setelah Anda memahami bagian-bagian itu, tentu saja, dan setelah mendapatkan komitmen dari atasan Anda bahwa ini akan baik-baik saja. Jika Anda atau bos Anda takut Anda dapat merusak sesuatu dengan menambahkan komentar, tambahkan mereka di cabang terpisah dan tanyakan kepada bos Anda apakah dia akan meluangkan waktu untuk meninjau komentar Anda sebelum mereka digabungkan ke bagasi. Karena atasan Anda hanya memiliki anggaran waktu terbatas, cobalah untuk mencari tahu apa yang dilakukan oleh bagian tertentu sendiri dengan menginvestasikan jumlah waktu yang masuk akal. Jika Anda benar-benar macet, tuliskan pertanyaan Anda di daftar dan tanyakan kepada bos Anda, misalnya, sekali sehari alih-alih mengganggunya selama 30 menit. Menurut pengalaman saya, pendekatan ini bekerja dengan kebanyakan orang, bahkan jika mereka sangat sibuk, selama mereka bersedia membantu Anda - yang tentunya merupakan kasus dalam situasi Anda.

Dengan cara ini, Anda yakin Anda mendapatkan komentar yang Anda butuhkan, dan bos Anda akan melihat di mana Anda membutuhkan informasi tambahan, dan jika Anda melakukan sesuatu dengan benar. Dan selama Anda membatasi diri untuk hanya mengomentari hal-hal yang tidak jelas, ada kemungkinan besar komentar Anda akan meningkatkan kualitas keseluruhan basis kode, yang mungkin tidak hanya membawa manfaat tidak hanya untuk Anda, tetapi juga untuk semua orang yang harus berurusan dengan kode, termasuk bos Anda.


3
Anda juga bisa mengusulkan tambalan menambahkan beberapa komentar ke atasan Anda.
Basile Starynkevitch

2
@BasileStarynkevitch: tentu saja, untuk menghindari risiko melanggar sesuatu, dia dapat menambahkan komentar di cabang terpisah terlebih dahulu dan meminta bosnya untuk meninjau komentar sebelum mereka digabungkan ke bagasi.
Doc Brown

2
@DocBrown Bekerja di cabang terpisah adalah strategi yang baik secara umum, tetapi jika menambahkan komentar merusak sesuatu, maka saya akan mengatakan basis kode memiliki masalah yang lebih besar ......
CVn

1
@ MichaelKjörling: sebenarnya, itu adalah sesuatu yang harus dibicarakan OP dengan bosnya. Menggunakan cabang yang berbeda memiliki dua keuntungan: ia menghindari jeda yang tidak disengaja dengan membuat kesalahan ketik seperti menghapus satu baris terlalu banyak saat menghapus komentar yang usang, dan mendorong bos untuk meninjau komentar.
Doc Brown

@ MichaelKjörling ini bukan tentang komentar yang merusak sesuatu, tetapi komentar tersebut harus sesuai dengan kode aktual.
Hugo Zink

8

Pertama-tama biarkan ini menjadi contoh bagi Anda untuk mengomentari kode Anda dengan benar, belalang!

Lalu, saya harus melakukan ini sepanjang waktu. Saya sudah memeriksa salinan lokal saya, dan saya memeriksanya dan berkomentar sendiri. (Saya bisa melepas mereka semua lagi jika saya ingin memeriksanya kembali - atau meninggalkan mereka, jika tidak ada yang keberatan.) Kemudian ketika saya benar-benar tidak dapat melihat lebih jauh, saya dapat bertanya kepada seseorang, di sini, saya pikir itu benar. ini (apa yang saya komentari), apakah saya benar? Jadi Anda mungkin telah melakukan komentar sebenarnya, tetapi sudah selesai dan itulah intinya.


5

Ini lebih dari sekadar permintaan pribadi. Anda mencoba mengubah kebiasaan / budaya, dan itu tidak mudah. Ini tentu saja bukan sesuatu yang dapat dicapai dengan percakapan lorong atau email. Ini akan membutuhkan usaha dari Anda.

Jadilah perubahan yang ingin Anda lihat di dunia.

Kutipan itu mungkin secara keliru dikaitkan dengan Mahatma Gandhi, tapi itu saran yang berlaku. Saat Anda mencoba memecahkan basis kode, tulis komentar yang ingin Anda lihat, sesuai kemampuan Anda, dan lakukan, setelah ditinjau oleh bos Anda. Keuntungan:

  • Anda bersikap proaktif, bukannya mengomel.
  • Anda memberi contoh yang baik. Dalam kasus terbaik, atasan / tim Anda akan melihat manfaat dan mengikutinya.
  • Beberapa komentar mungkin akan mengatakan /* Mystery parameter 3 */atau /* 2015-02-09 AidanQuinn: Is this code ever called? */- itu adalah peluang bagi kolega Anda untuk mendokumentasikan kode dengan benar atau memperbaiki bug laten.
  • Jika, selama tinjauan pra-komit, diketahui bahwa komentar yang Anda tulis tidak akurat, maka kolega Anda sekarang tahu bahwa kode itu tidak jelas.

Menahan diri dari penulisan ulang atau refactoring apa pun saat Anda melakukan ini, dan pengenalan komentar harus hampir bebas risiko. Jika Anda menulis ulang apa pun, simpan perubahan itu sebagai komitmen terpisah.

(Namun, sebelum Anda memulai proyek ini, pastikan bahwa harapan Anda untuk komentar masuk akal. Jika ide Anda tentang kode yang dikomentari dengan baik di luar norma ( Contoh 1 , Contoh 2 ), maka Anda hanya akan membodohi dirimu sendiri.)


5

Saya tidak akan meminta komentar tambahan, tetapi berikut adalah beberapa ide untuk Anda:

  1. Jadwalkan duduk bersama bos Anda dan minta dia membaca kode di tingkat tinggi. Ini seharusnya membuatmu memulai. Saya akan berharap beberapa jam hingga mungkin setengah hari sehingga Anda dapat mempercepat. Ini harus mencakup desain keseluruhan, pola yang digunakan, dll.
  2. Buat proyek pengujian dan mulailah menulis unit test terhadap kode, ini akan membantu Anda memahaminya tanpa memengaruhinya. Anda juga dapat menemukan beberapa bug!
  3. Debug kode sesuai kebutuhan untuk memahami area tertentu.
  4. Ambil peningkatan atau bug dari backlog dan kerjakan.

Komentar OK, tetapi jika kode ditulis dengan cara yang lurus ke depan itu harus dimengerti setelah beberapa hari.

Juga jangan berharap untuk memahami semuanya, lebih baik untuk fokus pada bidang utama terlebih dahulu dan kemudian memperluas pengetahuan basis kode yang diperlukan.


2

Saya telah berada dalam situasi yang sangat mirip dengan Anda kira-kira setahun yang lalu. Saya mulai bekerja dengan sedikit pengalaman pemrograman (meskipun saya tahu sedikit OO dan beberapa bahasa lain untuk memulai) dan satu orang yang mengajar saya hanya punya sedikit waktu. Dia selalu membantu, tetapi saya merasa tidak ingin menanyakan setiap pertanyaan yang saya miliki.

Orang lain telah menyarankan hal-hal yang sangat membantu di sini (misalnya menulis unit test, tetapi dari pengalaman saya sendiri, itu adalah sesuatu yang akan sedikit 'terlalu jauh' bagi saya dari awal; atau mengomentari bagian dari kode sendiri, tetapi itu mungkin sulit tergantung pada poin / pertanyaan pertama yang akan saya tanyakan sebentar lagi). Poin-poin berikut merangkum apa yang saya lakukan dan apa yang membantu saya, tetapi itu sangat tergantung pada di mana tepatnya masalah Anda berada.

Juga, saya harus setuju dengan @AK_ yang mengatakan bahwa Anda tidak benar-benar membutuhkan komentar dalam C #. Itu mungkin tidak 100% benar (saya merasa ada area di mana komentar pasti membantu, misalnya kode refleksi-berat) tetapi pada dasarnya itu. Jika Anda benar-benar menulis 'kode bersih' dengan metode dan variabel bernama baik, dan memiliki banyak 'kode' kecil, kode-kode itu hampir tidak diperlukan. Setiap kali saya merasakan perlunya komentar ketika membaca kode sejauh ini, kemudian setelah saya mengerti apa yang dilakukannya, saya sangat tidak senang dengan cara itu dilakukan dan berpikir itu bisa menjadi jauh lebih jelas di tempat pertama dengan refactoring yang baik. Sunting: Saya secara khusus berbicara tentang komentar C # di sini, bukan dokumentasi (baik itu dokumentasi terpisah atau komentar XML), karena menurut saya dokumentasi itu selalu penting.

  • Identifikasi apa sebenarnya masalah Anda dan apakah Anda dapat mengategorikannya. Artinya, apakah Anda masih memiliki masalah dengan bahasa itu sendiri atau tidak mengerti sintaksis tertentu (misalnya ekspresi lambda dan LINQ secara umum, atau Refleksi)? Jika Anda tidak mengerti baris kode, Anda tidak akan mengerti apa yang dilakukan seluruh metode / blok, jadi berkomentar sendiri akan sulit. Alih-alih, dapatkan buku yang bagus ('C # in a Nutshell' itu untuk saya, tetapi saya mendengar 'C # in Depth' juga spektakuler) dan membaca tentang hal-hal yang Anda temui. Mengkategorikan masalah-masalah ini sebelumnya membuat ini lebih mudah, karena Anda dapat mengisi 'kesenjangan yang lebih besar' sekaligus, atau bahkan bertanya kepada bos Anda tentang hal itu, karena itu tidak banyak pertanyaan lagi, tetapi lebih menjelaskan satu subjek atau konstruksi yang paling umum digunakan sehingga Anda bisa mendapatkan 'dorongan' yang sangat besar

  • Sejalan dengan yang di atas, saya mencoba membuat diri saya terbiasa dengan 'pengkodean bersih' dan praktik umum terbaik (bukan khusus bahasa). Efek dari ini mungkin tidak langsung, tetapi itu akan membayar cepat atau lambat, baik ketika Anda harus memperluas barang-barang yang ada atau bertanya-tanya mengapa seseorang menciptakan begitu banyak metode kecil alih-alih satu di mana semuanya terkandung ;-)

  • Dapatkan pemahaman tentang pola desain umum. Mereka mungkin muncul di sana-sini dalam kode yang Anda baca, dan jika Anda mengenalinya itu akan segera memberi Anda waktu. Bahkan jika Anda mengerti apa kode yang Anda lihat di sana, itu mungkin membuat Anda bertanya-tanya mengapa itu dilakukan dengan cara ini, dan mencari tahu sendiri semuanya seringkali tidak mudah.

Tolong jangan mengambil teks di atas karena saya membuat asumsi tentang 'keterampilan' Anda, saya sering tidak sengaja beralih antara berbicara tentang pengalaman saya dan berbicara 'kepada Anda'. Sebagian besar dimaksudkan sebagai apa yang saya temui , dan apa yang saya lakukan . Seperti yang orang lain katakan, ini bisa menjadi pengalaman yang sangat bagus dan cukup standar dalam pekerjaan untuk membaca kode yang bukan milik Anda dan Anda tidak tahu banyak tentang sebelumnya. Tetapi dapat benar-benar memuaskan untuk akhirnya memahami apa yang terjadi di sana dan mengenali diri Anda menjadi lebih baik pada 'keterampilan' khusus ini. Ambil ini sebagai kesempatan untuk belajar banyak dalam waktu yang sangat singkat, semoga berhasil! :)


1

Anda mungkin tidak akan membuatnya mengubah gayanya.

Yang bisa Anda lakukan adalah mengajukan banyak pertanyaan, dan menuliskan jawabannya.

Saya mewarisi basis kode besar di pekerjaan terakhir saya, sedikit dokumentasi dan beberapa komentar. Jadi saya akan mencoba selama setengah jam pada masalah yang sama, maka jika saya masih tidak bisa mengatasinya, saya akan bertanya kepada seseorang yang entah menulisnya, atau tahu bagaimana menggunakannya. Kemudian saya akan mendokumentasikan semua hal yang dia katakan kepada saya. Sebagian besar masuk dalam dokumentasi kami, beberapa masuk dalam kode sebagai komentar. Setelah setahun di sana saya praktis menulis sebagian besar dokumentasi kami dan saya tahu banyak tentang basis kode.

Semoga berhasil!


1

Saya mengalami masalah yang sama. Saya mahasiswa phyzist dan memiliki pengalaman pemrograman yang baik. Saya memprogram dalam banyak bahasa tetapi tidak untuk aplikasi premium.

Saya telah melamar pekerjaan untuk pengembang web dan mereka langsung menempatkan saya di belakang pemrograman web. Ketika bos menunjukkan saya api dasar untuk aplikasi simpul REST saya berpikir bahwa saya akan membuang. Saya belum pernah melihat fungsi dengan callback dan sintaks yang sangat aneh. Dan saya bertanya kepada bos saya apakah saya memiliki masalah Jika saya tidak mengerti apa pun dalam kode. Dia sedih tidak, dia sedih bahwa saya punya 1 bulan untuk mengetahuinya dan sementara itu saya akan membuat CMS untuk menguji saya dengan frontender lain.

Yah dan saya pergi 1 baris kode pada saat itu dan google setiap hal yang saya belum tahu. Jadi 1 minggu berlalu dan saya cukup akrab dengan kode sehingga saya bisa membuat beberapa kolaborasi dengan front ender. Kode saya di beginig adalah omong kosong tapi lihat saya 3 bulan setelah itu! Saya mengkode lebih baik dan lebih cepat daripada arsitek perangkat lunak kami!

Saya harap Anda tidak pernah berhenti belajar! Moto saya -> Terus belajar dan tetap tenang :) Jangan bergantung pada bos menjadi mandiri dan bertanya langsung tetapi hanya masalah yang paling sulit. Karena Anda akan bahagia setelah Anda mengetahuinya dengan resarch Anda sendiri. Dan ingat ketika Anda berhenti belajar sesuatu yang salah, pelajari hari sebelumnya bagaimana menjadi programmer yang baik.

Jika Anda akan belajar dari bos, Anda tidak akan pernah lebih baik daripada dia menetapkan standar Anda sendiri, belajar pengetikan buta, VIM atau VIM plugin untuk IDE Anda, Linux wmii, sehingga suatu hari Anda akan melampaui bos, dan lebih baik daripada dia!


posting ini agak sulit dibaca (dinding teks). Maukah Anda mengeditnya menjadi bentuk yang lebih baik?
nyamuk

Maaf atas ketidaktahuan saya :)

posting yang diperbarui jauh lebih mudah untuk dipahami (edit yang baik!) tetapi apa yang dapat saya lihat sekarang tampaknya hanya mengulangi poin yang sudah dibuat (dan jelas dijelaskan lebih baik) dalam jawaban sebelumnya, terutama dalam yang ini
agas

1
Saya minta maaf saya melakukan ini di pagi hari sebelum pekerjaan dan saya tidak punya banyak waktu di tangan saya, tujuannya adalah bahwa pemilik pertanyaan akan melihat, untuk poin saya tidak peduli :)

0

Sebagai seorang insinyur perangkat lunak yang telah berdiri selama 20 tahun, kebanyakan bekerja pada hal-hal yang berhubungan dengan keselamatan (SF-PD), saya harus mengatakan bahwa atasan Anda mungkin bukan orang yang Anda inginkan sebagai teladan Anda. Kurangnya komentar adalah pertanda baik seorang programmer amatir otodidak yang tidak pernah belajar bagaimana melakukan pekerjaan dengan baik, atau insinyur yang tidak berpengalaman. Atau mungkin seorang insinyur yang tidak punya waktu - tenggat waktu dan kebijaksanaan dapat melakukan hal-hal mengerikan pada kode Anda! ;) Ini jelas merupakan anti-pola untuk setiap insinyur perangkat lunak yang kompeten.

Bos Anda mungkin pembuat kode yang sangat bagus, tetapi sepertinya ia bukan insinyur perangkat lunak yang baik. Seorang insinyur menggunakan pengalaman kelompok kolektif untuk menghindari jebakan yang telah ditangkap orang lain. Komentar yang efektif adalah bagian dari pengalaman kelompok kolektif untuk perangkat lunak, dengan cara yang sama seperti analisis stres adalah bagian dari pengalaman kelompok kolektif untuk teknik mesin. Apa yang dianggap komentar efektif lebih lancar, dan itu pasti sesuatu yang Anda dapatkan dari pengalaman.

Yang paling mendasar adalah bahwa komentar tidak boleh mengatakan apa yang dilakukan oleh baris kode. Ada saat-saat ketika komentar untuk mengatakan apa fungsi tidak terlalu berlebihan (terutama di C #). Mengomentari berlebihan bisa sama tidak efektifnya (dan menunjukkan kurangnya pengalaman) karena Anda tidak dapat menemukan hal-hal penting dalam sampah. Sebagai seorang pemula, Anda mungkin masih berusaha mencari tahu "apa" dari kode itu, dan untuk itu Anda hanya perlu membaca dan memahami apa yang dia lakukan.

Yang penting untuk komentar adalah bahwa mereka mengatakan MENGAPA sebaris kode atau fungsi melakukan apa yang dilakukannya, di mana ini mungkin tidak jelas. Apakah Anda perlu mengatur modul X sebelum modul Y? Apakah penting untuk memeriksa kode kembali untuk melihat apakah suatu file sudah terbuka, atau apakah kita secara sadar mengabaikan kode kembali karena ini telah diperiksa di tempat lain? "Mengapa" kode akan relevan bagi semua orang, terlepas dari pengalaman - dan itu akan relevan baginya juga dalam waktu 6 bulan, ketika dia lupa tentang alasan yang baik untuk melakukan sesuatu dengan cara tertentu. Mengomentari bukan hanya untuk orang lain, itu untuk membantu Anda di masa depan juga.

Jika Anda ingin menghindari gangguan bos Anda, ajukan pertanyaan pintar. Berfokuslah pada pertanyaan tentang "mengapa", dan coba cari tahu sendiri "apa" (kecuali itu benar-benar tidak jelas). Tidak ada bos yang baik yang keberatan mengajukan pertanyaan jika itu bukan hal yang dapat Anda temukan dari R-ing TFM. Dan tidak ada insinyur yang baik akan keberatan diminta untuk melakukan sesuatu yang akan membuat hidup insinyur lain secara signifikan lebih mudah, dengan sedikit biaya bagi mereka. (Hanya saja jangan memintanya untuk mengisi komentar pada seluruh basis kode!;)


1
Paragraf pertama menyiratkan bahwa bos — dan sebagian besar dari kita — tidak kompeten karena dia (diasumsikan) tidak berkomentar seperti yang seharusnya. Sangat disayangkan, karena sisa saran tentang kapan dan bagaimana berkomentar sebenarnya cukup masuk akal. Sebagian besar dari kita mungkin akan setuju jika kita tidak menunda pada awalnya.
John M Gant

Tiga paragraf terakhir dari jawaban Anda cukup berguna, @ Graham. Tolong jangan biarkan beberapa downvotes mengecilkan hati Anda.
DavidS

Saya terkejut melihat downvotes. Informasi tentang apa, bagaimana, dan mengapa berkomentar sudah mati. Saya setuju dengan orang lain bahwa spekulasi Anda tentang kompetensi bosnya tidak produktif.

@ Superstringcheese: Sayangnya, Anda sering mendapatkan downvotes karena memegang posisi selain "Mom and apple pie". Saya tidak setuju dengan beberapa dari apa yang Anda katakan (bukan paragraf pertama! Ini IMO yang benar-benar valid) - tetapi Anda masih mendapatkan suara positif pada prinsipnya.
einpoklum - mengembalikan Monica

0

Berada dalam situasi yang sama, saya katakan

  1. Bos Anda mungkin ingin Anda mempelajari cara kotor (dengan berjalan melalui kode yang tidak Anda ketahui) karena suatu alasan. Ini adalah cara kita belajar lebih banyak dalam sebulan di tempat kerja daripada satu tahun di perguruan tinggi sebagaimana disebutkan dalam jawaban lain.

  2. Ini adalah "norma" sebagaimana disebutkan dalam jawaban lain. Anda harus lebih khawatir tentang di mana untuk memulai dan bagaimana mendekati dan apa yang harus difokuskan daripada mencoba memahami setiap baris kode segera. Tanyakan kepada atasan Anda tentang alat yang tepat dan cara untuk debug / langkah melalui kode. Pertanyaan semacam ini akan memberi Anda beberapa poin.

  3. Secara teratur, terus mendekati bos Anda untuk mendapatkan umpan balik tentang bagaimana Anda melakukannya sehingga Anda akan mendapatkan ide di mana Anda berdiri dalam persentil dengan asumsi bos Anda telah melihat banyak orang dalam situasi yang sama dan memiliki ide bagaimana mereka melakukannya.

  4. Ambil ini sebagai peluang dan saat Anda menjadi lebih baik dengan memahami kode, terus tambahkan komentar yang semula Anda harapkan untuk ditanyakan kepada bos Anda.


0

Jika Anda benar-benar ingin mencoba memintanya untuk memberikan komentar dalam kodenya (saya tidak merekomendasikannya), saya sarankan mencari kode yang perlu Anda edit yang benar-benar dapat menggunakan beberapa komentar (kebanyakan cukup jelas) dan menanyakan pertanyaan tentang seperti ini "Saya melihat kode ini di sini dan saya mencoba mencari tahu [Masalah yang Anda alami] dan saya tidak dapat menemukan komentar untuk membantu menjelaskannya". Pada dasarnya cobalah untuk menunjukkan bahwa Anda telah berupaya memahami dan menjelaskan mengapa Anda berdua bisa mendapatkan manfaat dari komentar yang ada.

Mungkin 90% dari kode yang ditulis dengan baik tidak perlu komentar. Anda hanya benar-benar ingin mendokumentasikan bagian-bagian kode yang telah dioptimalkan dan menjadi agak tegang. Saya pernah bekerja di sebuah perusahaan yang mengharuskan Anda untuk mendokumentasikan setiap bagian dari kode yang Anda modifikasi pada dasarnya, komentar-komentar tersebut akhirnya secara aktif merugikan keterbacaan kode karena sering merujuk pada kode yang telah dihapus atau dimodifikasi tanpa bisa dikenali. Waspadalah terhadap komentar yang buruk. Saya menghabiskan satu minggu men-debug sebuah fungsi dan pada akhirnya saya menemukan bahwa komentar yang terus saya baca tentang pengaturan flag ini dan itu menjadi "false" sebenarnya adalah keseluruhan masalah yang saya atur flag menjadi "true" dan semuanya bekerja seperti yang seharusnya.


1
Kode yang tidak dikomentari bukanlah kode yang ditulis dengan baik. Saya memberi tahu pengembang saya untuk memberi komentar di awal setiap blok sebagai aturan praktis. Atau tulis ulang blok menjadi metode dengan nama yang mendokumentasikan diri. Kecuali jika metode Anda adalah pernyataan if, panggilan metode, dan pengembalian, Anda perlu komentar.
Pengingat kaya

@richremer Saya pikir kita hampir sepenuhnya sepakat. Saya bertujuan untuk mendokumentasikan kode diri dengan komentar di mana segala sesuatu menjadi tegang.
dkippers

0

Jika Anda ingin komentar dalam kode memahami mengapa sesuatu telah ditulis maka kemungkinan besar (mengingat Anda baru), Anda belum memahami kebutuhan bisnis. Saya yakin Anda tahu semua sintaks dan dapat membaca kode tetapi kecuali jika Anda tahu tujuan dari beberapa kode maka Anda akan merasa sedikit tersesat.

Satu hal yang muncul di pikiran adalah pemrograman pasangan. Anda mengatakan bahwa bos Anda terkesan dengan kemajuan Anda sehingga Anda bisa menyarankan bekerja bersamanya. Ini akan membantu Anda berdua dalam jangka panjang. Bos Anda akan menemukan dirinya harus menjelaskan hal-hal yang dianggapnya wajar dan Anda akan belajar lebih banyak tentang bisnis ini.


0

Seperti yang disebutkan orang lain, ini sangat umum, tetapi itu tidak berarti Anda hanya perlu menyedotnya dan membajaknya. Anda tidak perlu memahami sebanyak mungkin kode sebanyak yang Anda pikir Anda lakukan, dan ada strategi konkret untuk membuat "ujung yang dalam" jauh lebih dangkal:

  • Temukan sesuatu dalam kode yang terkait dengan tugas yang ada. Biasanya yang paling mudah dicari adalah sesuatu yang terlihat oleh pengguna, seperti label tombol pada GUI. Tuliskan di mana Anda menemukannya. Ini akan menjadi titik jangkar Anda.
  • Sekarang cari kode satu langkah lagi dan tulis itu. Siapa yang menciptakan tombol? Kode apa yang dipanggil ketika tombol diklik?
  • Kontrol sumber sering kali berguna untuk menemukan kode yang selangkah lagi. Cari kapan kode yang Anda cari ditambahkan atau diubah, dan lihat apa lagi yang diperiksa pada saat yang sama, dan mengapa.
  • Ulangi sampai Anda cukup mengerti untuk melakukan perubahan, ditambah satu level lebih dalam untuk memastikan Anda tidak melewatkan apa pun.
  • Jika Anda terjebak pada suatu titik, Anda sekarang memiliki pertanyaan yang sangat spesifik untuk ditanyakan. Misalnya, "Saya tidak tahu dari mana tombol ini digunakan."

0

Ini adalah $ 0,02 saya tentang masalah ini. Saya tidak menyarankan jawaban eksklusif, banyak dari apa yang telah dikatakan di sini cukup relevan.

Saya akan mencoba sedikit rekayasa sosial untuk mengatur hal-hal sehingga bos Anda merasa lebih mudah / kurang memakan waktu untuk mengomentari beberapa kode-nya daripada tidak.

Sekarang, ini bisa sangat mudah jika Anda bersedia mengambil risiko besar dan mengganggunya - tetapi kami tidak ingin melakukan itu. (catatan: Anda bisa gagal melakukan apa pun tanpa dia menulis atau mendikte komentar kepada Anda, Anda bersikeras dan mengganggu dia tentang hal itu tanpa henti dll.)

Apa alternatifnya? Beberapa ide, tergantung keadaan.

Pilihan 1

  1. Luangkan waktu untuk memahami sepotong kode sebagai melakukan X.
  2. Sekarang pikirkan cara yang masuk akal Y untuk salah paham .
  3. Beri tahu bos (melalui email atau katakan saat sarapan atau apa-tidak) bahwa Anda saat ini sedang berusaha mencari tahu.
  4. Tambahkan komentar yang mengatakan tidak jelas apa artinya kode, tetapi Anda memahaminya sebagai Y; coba buat komentar ini terlihat olehnya - tetapi jangan berusaha terlalu keras!
  5. Bertindaklah dengan asumsi Y - dan pastikan bos Anda memperhatikan tindakan Anda (sehingga Anda tidak membuang waktu untuk waktu yang lama dengan asumsi yang salah).
  6. Bos harus mengambil inisiatif untuk mengoreksi Anda. Pada titik ini, katakan padanya sesuatu seperti "Saya benar-benar berharap kode ini memiliki beberapa komentar untuk mencegah saya membuat asumsi yang salah. Saya akan memperbaiki komentar yang saya tambahkan untuk diri saya sendiri. Apakah Anda mengira Anda dapat membantu saya dengan beberapa deskripsi umum? potongan-potongan kode ini-itu? Saya tidak cukup berpengalaman untuk mengetahui maksud yang tepat, dan saya hanya beberapa kalimat yang akan melakukan trik. " Atau sesuatu..

pilihan 2

Anda sedang berlatih. Cobalah untuk mengatur pertemuan mingguan frekuensi tetap (tambahan?) Dengannya. Pada pertemuan ini, bacalah beberapa kode - tetapi Anda harus cukup siap agar dia tidak harus menjelaskan setiap baris. Pada titik tertentu - mudah-mudahan - dia akan menyadari bahwa dia dapat melewatkan pertemuan jika dia hanya menambahkan komentar.

Opsi 3

Dapatkan rekan kerja lain untuk gagal memahami kode yang sama dengan Anda. Anda berdua mendekati bos di waktu yang berbeda untuk mengajukan pertanyaan yang sama. Itu cara yang pasti untuk membuatnya sadar bahwa dia gagal melakukan sesuatu ... tetapi tidak semua orang memiliki kemewahan rekan kerja yang membantu dalam proyek yang sama.


0

Jadi hanya sesuatu yang akan membantu saya sampai saya bisa menguasai beberapa hal, bagaimana saya bisa meminta atasan saya untuk memberikan komentar ke dalam kode yang dia berikan kepada saya, tetapi dengan sopan?

Jika Anda tidak dapat memahami kode tersebut, mengapa menurut Anda komentar tersebut adalah solusi Anda?

Saya tidak tahu gaya pemrogramannya, tetapi saya akui bahwa jika nama fungsi dan variabel menyesatkan, itu membuat memahami kode sangat sulit. Tetapi jika nama dan fungsi atau bahkan organisasi program (kelas, metode, properti ...) sedemikian sehingga membuat kode dimengerti, maka kode tersebut sebenarnya akan berbicara kepada Anda dengan sendirinya.

Anda sebaiknya memintanya untuk arsitektur program dan jika Anda ingin memintanya untuk sesuatu, mintalah beberapa nama untuk fungsi yang lebih bermakna; itu lebih nyaman baginya untuk melakukannya.


0

Bahkan jika ada cara untuk menanyakan hal ini dengan sopan, ada dua kemungkinan tentang apa yang akan dipikirkan atasan Anda tentang komentar dalam kodenya:

  1. Entah itu komentar dalam kodenya akan menjadi hal yang baik untuk dimiliki, atau

  2. Komentar dalam kodenya bukan hal yang baik untuk dimiliki.

Jika bos Anda berpikir bahwa komentar dalam kodenya tidak akan menjadi hal yang baik untuk dimiliki, (dan ada argumen yang sangat bagus untuk ini, yaitu kodenya seharusnya menjadi dokumentasi , dan tidak ada dokumentasi yang akan menetapkan sesuatu secara tepat dan tidak ambigu. sebagai kode yang benar-benar melakukannya ,) maka tidak ada yang akan terjadi.

Sekarang, jika kebetulan bos Anda berpikir bahwa komentar dalam kodenya akan menjadi hal yang baik untuk dimiliki, maka ada kemungkinan besar ia akan meminta Anda untuk mempelajari kodenya, memahami cara kerjanya, dan melanjutkan untuk menambahkan komentar ke kodenya. kode sendiri . (Ada argumen yang sangat bagus untuk ini juga, yaitu Anda perlu belajar , dan waktunya menurut definisi jauh lebih berharga daripada milik Anda .)

Jadi, kecuali Anda siap untuk melakukan ini, Anda mungkin lebih baik tidak mengatakan apa-apa.

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.