Bos saya menginginkan penjelasan bahasa Inggris baris demi baris dari kode kami


155

Saya telah secara khusus diminta untuk memberikan penjelasan atau komentar per baris (atau yang sesuai - misalnya, gambar per gambar, dll.) Yang ingin dibaca dan diikuti oleh bos saya.

Karena dia bukan seorang programmer, dia tidak bisa mengikuti kode sehingga ingin semuanya diterjemahkan ke dalam bahasa Inggris.

Adakah yang pernah diminta melakukan ini sebelumnya?

Saya telah mengomentari semua kode sumber dan menggunakan JSDoc untuk menghasilkan dokumentasi lengkap dari semua fungsi, variabel, dll ... dan termasuk contoh implementasi, dan demo kerja penuh dengan komentar di seluruh.

Apakah ada hal lain yang bisa saya lakukan untuk mengomentari kode untuk yang bukan programmer?

Ini bukan permintaan yang masuk akal, bukan?


MEMPERBARUI

Pada akhirnya, saya berhasil menjelaskan mengapa itu bukan penggunaan waktu yang baik untuk melakukan apa yang dia minta. Dia adalah pria yang masuk akal, dan hanya tidak memiliki pemahaman tentang apa yang melibatkan pekerjaan saya. Begitu dia melihat posting ini, saya pikir dia cepat mengerti bahwa itu bukan permintaan normal.

Saya memang menyediakan dokumentasi yang cocok untuk diikuti oleh programmer lain (JSDoc dan komentar inline - serta beberapa catatan tambahan tentang masalah teknis), dan diagram alir yang sangat luas dari logika utama program untuk diikuti bos saya.

Pada akhirnya, semua pihak merasa puas dan kami telah pindah.


Terkunci karena alasan historis, silakan lihat "Kunci pertanyaan-pertanyaan terpilih yang ditutup" untuk perincian lebih lanjut.
yannis

Jawaban:


160

Tidak , ini bukan permintaan yang masuk akal!

BICARA DIA DARI ITU , atau mintalah orang lain membicarakannya, dengan segala cara. Itu adalah ide yang irasional, yang walaupun bisa dilakukan sangat mahal untuk dilakukan tetapi seharusnya tidak pernah dilakukan. Tinjauan fungsi dan subrutin masuk akal, tetapi untuk "menjelaskan" setiap baris kode tidak. Akan lebih efektif baginya untuk belajar membaca bahasa di tangan, daripada melakukannya.

Hal berikutnya yang akan ia minta adalah menerjemahkan rumus matematika, atau yang lainnya ke dalam teks bahasa Inggris. Meskipun tentu saja mungkin itu memperkenalkan banyak ruang untuk kesalahan dan salah tafsir , dan tidak boleh dilakukan. Sama seperti "menerjemahkan" kode ke bahasa Inggris.


Menarik: Pergi baca Richard Feynmans kuliah tentang Fisika. Anda akan menemukan bahwa sebagian besar dari itu adalah argumen yang ditulis dengan hati-hati, dalam bahasa Inggris (jika X maka Y pasti benar, dan karenanya Z ... dll). Matematika kecil. Maksud saya adalah Anda dapat menjelaskan banyak hal dalam bahasa Inggris. Apakah Anda HARUS merupakan masalah lain?
cepat_now

1
@quickly_now - Membacanya lama di masa kuliah. Bukan bacaan yang buruk. Saya setuju, Anda bisa menjelaskannya - Anda bisa menjelaskannya dalam bahasa apa pun ketika orang yang Anda jelaskan sudah memahami "abstraksi" di belakangnya (kode, persamaan matematika, dan artinya ...) // Jika dia tidak t - Anda akan kesulitan menjelaskannya dalam bahasa apa pun.
Benteng

4
@Rook - poin bagus. Menjelaskan mekanika kuantum kepada suku primitif yang perbendaharaan katanya terbatas ke arah mana Rusa itu akan bergerak agak sulit.
cepat_now

Saya bisa mendapatkan 'niat' manajer Anda sesekali untuk mengelola mikro. Tapi, jika kodenya sangat jelas, maka dia bisa membacanya sebagai teks bahasa inggris.
Arvind Chinniah

150

Apakah Anda memiliki dokumen desain ? Itulah penjelasan bahasa Inggris tentang apa yang dilakukan kode. Manajer non-pemrograman tidak perlu lebih dari itu.


15
Itulah sebabnya saya menetapkan, "Manajer non-pemrograman tidak perlu lebih dari itu."
Malfist

35
@ Loren Pechtel: Saya ingin situs di sana dan menonton orang ini benar-benar membaca halaman "Buat variabel integer bernama X. Atur ke 0. Buat variabel integer bernama Y. Atur ke 0. Buat variabel integer bernama Z Setel ke 0. Buat variabel integer bernama posisi X. Setel ke 0. Buat variabel integer bernama posisi Y. Setel ke 0. Buat variabel integer bernama posisi Z. Setel ke 0. Buat variabel integer bernama posisi X Rotasi X. Atur ke 0. Buat variabel integer bernama rotasi Y. Setel ke 0. Buat variabel integer bernama rotasi Z. Atur ke 0. "...
FrustratedWithFormsDesigner

9
@Frustated Jauh lebih mudah dengan penyorotan sintaks! " [p32767, l21, c8] Menambah pXukuran a Integer. Menambah Sumnilai yang ditunjukkan oleh pX. Menambah i1. Jika ikurang dari 3, buka halaman 32768, baris 17, kolom 42. Jika tidak, buka halaman 32767 , baris 21, kolom 8. "
Mateen Ulhaq

9
@muntoo, Anda harus menyejajarkan semua fungsi itu sehingga Anda tidak harus bolak-balik di antara halaman. Kalau tidak, orang mungkin memiliki banyak kesulitan untuk kembali ke tumpukan.
Kibbee

15
@ Frustasi: Jadi suara siapa yang kamu bayangkan? Saya tidak bisa memutuskan antara Sean Connery dan Morgan Freeman.
Beta

113

Apakah ada penghargaan manajer-mikro tahun ini? Sepertinya bos Anda layak dinominasikan. Seseorang yang percaya bahwa dia membutuhkan pemahaman tingkat kode baris-per-baris, tetapi tidak ingin belajar cara membacanya secara langsung, hampir sempurna seperti manajer mikro seperti yang bisa dibayangkan.

Salah satu keuntungan menjadi pengembang adalah bahwa sulitnya memahami kode mencegah manajemen mikro melampaui tingkat tertentu, setidaknya pada tingkat implementasi terperinci, setidaknya oleh manajemen non-teknis, karena bahkan manajer mikro yang paling keras pun mengakui bahwa mereka di atas kepala mereka di tingkat itu. Tapi kejeniusan bos Anda mungkin menemukan cara untuk menghancurkan tirai silikon.

Dan, sebagai bonus, itu membuang banyak waktu pengembang melakukan terjemahan, bahkan sebelum dia menggunakan terjemahan bahasa Inggris untuk mulai menyarankan berbagai perbaikan (saya berasumsi dia tahu bagaimana kode lebih baik daripada programmer, walaupun dia tidak bisa Baca kode, dan akan dapat membagikan kebijaksanaannya segera setelah seseorang menerjemahkannya, jika tidak, mengapa dia perlu setiap baris diterjemahkan?).

Jadi, tidak, itu bukan permintaan yang masuk akal, dan saya belum pernah mendengarnya sebelumnya. Dan aku merindukanmu. Saya pikir semua orang mungkin perlu mulai mencari pekerjaan lain dengan tenang, karena begitu dia mulai menggunakan terjemahan kode sebagai alat manajemen, itu mungkin akan menjadi tempat yang brutal untuk bekerja (eh, tempat yang lebih brutal untuk bekerja).

Di sisi positifnya, mungkin Anda bisa mendapatkan anti-pola baru bernama setelah situasi Anda? Bagaimana dengan anti-pola "Dirty Hungaria Phrasebook", setelah sandiwara Monty Python di mana seorang tobacconist berusaha berkomunikasi dengan seseorang yang tidak berbicara bahasa Inggris dengan menggunakan buku frase Hungaria yang memiliki terjemahan palsu yang lucu?


21
+1 untuk mendiagnosis manajemen mikro. Dengan kata-kata saya sendiri: keluarkan f___ dari sana!
tdammers

@tdammers: untungnya, ini adalah hal yang bisa saya katakan kepada bos saya. Dia teman baik selain menjadi bos!
heltonbiker

5
Seorang manajer yang perlu memahami setiap baris kode disebut programmer.
James P.

91

Duduklah bersamanya dan bicaralah melalui 10 baris kode. Jelaskan setiap detail sampai Anda berdua setuju bahwa ia memahaminya sejauh yang ia inginkan.

Mungkin pengalaman ini yang ia cari: hanya kesan seperti apa pekerjaan Anda bagi Anda, dan seperti apa perangkat lunak itu dari sudut pandang Anda. Itu hal yang baik dalam buku saya.

Jika setelah ini, dia masih ingin Anda melanjutkan, katakan: perhatikan berapa banyak pertanyaan yang harus saya tanyakan; bayangkan jika saya harus menjelaskan semua ini tanpa dapat mengajukan pertanyaan, bagaimana mungkin saya tahu apa yang harus dimasukkan dan apa yang harus ditinggalkan? Berapa lama waktu yang dibutuhkan sebelum hasilnya bermanfaat bagi Anda? Sekarang berapa banyak baris yang Anda ingin saya lakukan dengan cara ini?


57
Pastikan setelah Anda menghabiskan dua jam menjelaskan sepuluh baris yang ia pahami bahwa ada 50.000 (atau apa pun) baris kode yang tersisa untuk dijelaskan.
HLGEM

6
Sebenarnya cara yang sangat waras untuk menindaklanjutinya. Buat dia melihat ketidaktahuan jalannya.
Kibbee

4
@reinierpost: metode Anda jenius murni.
heltonbiker

5
Jika Anda akan melakukan ini, pertama katakan pada bos mengapa itu ide yang buruk secara umum dan MAKA menunjukkan. Jika tidak, ini mungkin tampak seperti Anda melakukan "tipuan" padanya dan menempatkannya pada posisi bertahan.
nerdytenor

5
Jangan pernah memberi tahu orang-orang bahwa ide mereka buruk !! Namun, Anda dapat mendiskusikan apa yang diperlukan untuk mewujudkannya, dan bahkan mungkin memberikan beberapa ide untuk mengambil jalan pintas. Jika ini mengarahkan mereka untuk menyimpulkan bahwa ide itu tidak layak, atau membuat ide awal berubah menjadi sesuatu yang sama sekali berbeda, dan mereka harus memperhatikan hal ini di beberapa titik, mereka akan mengangkat bahu dan berkata: itulah hidup.
reinierpost

43

Saya pikir itu bukan permintaan yang masuk akal. KODE SUMBER tidak dimaksudkan untuk dibaca dalam bahasa Inggris (atau bahasa lain apa pun dalam hal ini).

Mungkin dia takut Anda akan membuat kode Anda melakukan sesuatu yang tidak dia setujui atau sadari. Jika itu masalahnya, saya tidak berpikir ada sesuatu yang dapat Anda lakukan. Anda harus menulis dokumentasi atau mungkin meyakinkan dia untuk mempekerjakan seseorang untuk mengaudit kode Anda.


13
Bahkan dengan terjemahan bahasa Inggris, non-programmer mungkin sangat percaya:/* and this line is transferring deposits to the correct account */ deposits.TransferAll(acctInfo);
IAbstract

15
Jika bos "takut Anda akan membuat kode Anda melakukan sesuatu yang tidak ia setujui atau sadari" ini tidak akan melakukan apa pun untuk mengurangi ketakutannya. Orang yang sama menyediakan terjemahan yang menulis kode. Apa yang mencegah mereka berbohong tentang apa fungsinya? Ada hal lain yang terjadi di sini.
mmc

4
COBOL dimaksudkan untuk dibaca dalam bahasa Inggris.
oosterwal

1
Mungkin dia sedang mencoba mencari tahu apa yang dilakukan kode untuk melihat apakah dia setuju dengan alasan dan mungkin mendapatkan ide yang lebih baik. Bagaimanapun, itu bukan tugasnya untuk melakukannya, setidaknya tidak seperti itu ...
heltonbiker

32

Ini sangat sederhana:

  • Anda telah dipekerjakan karena keahlian Anda sebagai programmer
  • Manajer Anda tidak memiliki keterampilan ini
  • Ergo, manajer Anda seharusnya tidak cukup berharap untuk dapat sepenuhnya memahami apa yang Anda lakukan

Saya memiliki pengalaman serupa dengan ini di pekerjaan sebelumnya. Manajer saya adalah seorang akuntan (dan dengan demikian sangat berorientasi pada tingkat rendah), dan tidak mengerti atau benar-benar mempercayai pemrograman. Dia tidak dapat memahami bahwa dia, sebagai orang non-teknis, seharusnya tidak berharap dapat memahami hal-hal kecil dari apa yang saya tulis. Setelah banyak permintaan untuk dokumentasi yang berlebihan dan permintaan untuk melatih pengguna non-teknis tentang cara mengelola dan mengubah kode (ya, sungguh), saya berhenti mencoba untuk membuatnya kabur, dan langsung menolak. Analogi yang saya gunakan untuk menjelaskan itu sederhana:

  • Saya bukan seorang akuntan
  • Saya seharusnya tidak mengharapkan untuk memahami setiap transaksi atau posting di akun kami
  • Ini tidak berarti bahwa rekeningnya salah, atau tidak dapat dipercaya, hanya karena saya tidak memahaminya
  • Ini dimungkinkan dengan mempercayai orang yang menyusunnya

Pada akhirnya, inilah yang terdengar bagi saya: seorang manajer yang kesulitan mempercayai karyawan mereka; atau takut bahwa mereka akan pergi, dan berpikir bahwa ini adalah cara yang efektif untuk mengurangi terhadapnya.

Satu-satunya solusi untuk ini adalah duduk dan menjelaskan mengapa ini tidak masuk akal. Adalah tugas Anda untuk memahami kode dan memungkinkan seseorang dengan keterampilan yang sama dengan Anda untuk memahaminya, bukan milik manajer Anda. Menunjukkan kepada mereka utas ini mungkin ide yang bagus (atau yang benar-benar mengerikan, tergantung pada kepribadian mereka).


bagaimana manajer Anda mengambil penjelasan Anda?
Jeff Martin

1
Persis seperti yang Anda harapkan. ;) Namun, intinya telah dibuat, dan permintaan berhenti. Saya tidak tahu apakah itu karena saya telah meyakinkan dia akan validitas argumen saya atau dia memutuskan itu tidak sepadan dengan kerumitan dan menyerah.
John N

25

Baris demi baris, konyol. Apa yang saya sarankan adalah menawarkan untuk menghasilkan dokumen dari komentar dan memberikannya. Itu cukup untuk sejumlah hibah dan audit Pemerintah Kanada yang telah saya kerjakan di masa lalu.

Dia tidak akan mendapatkan baris-demi-baris tetapi dia akan mendapatkan metode-demi-metode yang seharusnya tetap lebih rinci daripada yang dia butuhkan.

Beberapa solusi yang ada, tergantung pada platform Anda:

  • C #: sandcastle
  • Java: javadoc
  • "C ++, C, Java, Objective-C, Python, IDL (rasa Corba dan Microsoft), Fortran, VHDL, PHP, C #, dan sampai batas tertentu D." : oksigen

Karena ada Pas2Dox, tambahkan Delphi ke daftar doxygen ;-)
Fabricio Araujo

Pergi ke tautan Sandcastle. Terlihat terkesan. Klik tab "Dokumentasi". Lihat pesan "Proyek ini belum memiliki dokumentasi." Terlihat kurang terkesan.
Kaz Dragon

16

Akan jauh lebih cepat baginya untuk belajar membaca kode daripada menerjemahkan seluruh kode aplikasi yang menarik ke bahasa Inggris. Selain itu, kami mencobanya dengan COBOL dan itu tidak membantu sama sekali. Jika dia tidak mau belajar, tetapi hanya ingin membuat ketidaktahuannya menjadi masalah orang lain, Anda memiliki bos yang berkepala runcing.


3
Saya pikir bahasa Inggris harus menjadi bahasa. Bos harus meminta semua perangkat lunak untuk ditulis dalam DSL (bahasa khusus domain), maka ia dapat membuat perubahan pada cara kerja sistem.
David d C e Freitas

Saya pikir penyebutan Cobol merangkumnya. Siapa pun yang mencetak dunia halo yang sederhana tahu betapa konyolnya bahasa ini. Itu adalah langkah yang baik menuju sesuatu yang dapat dipahami tetapi terlalu formal.
James P.

15

Gunakan keahlian teknis Anda untuk mengejar bos Anda.

  1. Biarkan dia tahu bahwa itu akan memakan waktu lama untuk melakukan ini seperti yang Anda lakukan untuk kode itu di tempat pertama (Jangan ragu untuk membuatnya lebih lama).
  2. Tanyakan kepadanya seberapa terbaru dokumen ini perlu. Beri tahu dia semua perubahan pengkodean sekarang akan memakan waktu setidaknya dua kali lebih lama.
  3. Jika Anda atau orang lain menemukan bug, tanyakan kepadanya apakah Anda harus memperbaikinya sekarang atau tunggu sampai Anda selesai melakukan pengkodean psuedo. Ingatkan dia tentang # 1 & # 2.

Seperti semua saran solusi buruk, lebih baik mengidentifikasi masalahnya. Mungkin atasan Anda terkena pertanyaan teknis oleh manajemen tingkat atas dan dia merasa malu karena dia tidak dapat menjawab. Mungkin ada satu bagian kode tertentu yang menurutnya paling dikhawatirkan, sehingga Anda bisa membatasi upaya besar ini hanya untuk area itu.

Dengan mengirimkan sampel, ia mungkin sampai pada kesimpulan bahwa jika Anda tidak mengerti bagaimana pengkodean bekerja (Apa itu loop dan apa yang dilakukan untuk semua item ini?) Tidak masalah apa bahasa itu. Dia lebih baik off memahami aplikasi dari perspektif pengguna daya. Saya pikir adil bagi Anda untuk memberi tahu dia bahwa Anda lebih suka menulis kode / petunjuk nyata - Saya sedang mencari pekerjaan lain.


7
kita perlu berhati-hati dalam mengkarakterisasi siapa pun sebagai "idiot". Meskipun secara pribadi memuaskan bagi kita sebagai programmer untuk melakukan ini, saya tidak berpikir itu profesional, dan setiap permintaan dari manajer mana pun, tidak peduli betapa anehnya, harus diperlakukan berdasarkan kemampuannya.
funkymushroom

6
@funkymushroom: Kelebihan dari permintaan ini adalah dia idiot.
DeadMG

3
@funkymushroom - Saya pikir kita bisa diizinkan sedikit kesembronoan di situs ini. Setelah semua, Anda pergi dengan funkymushroom.
JeffO

2
@ Jeff: Point diambil dengan baik. Aku sama sekali bukan tongkat. Namun, ada dua jenis "idiot". "Malicious Idiot" dan "Ignorant Idiot" dan saya telah bekerja dengan keduanya. Yang pertama harus diabaikan, dia berbahaya bagi karier kita, dan yang kedua bisa menjadi sekutu yang baik, jadi kita harus mengajarinya.
funkymushroom

@funkymushroom - setuju, jadi saya mengeluarkannya.
JeffO

12

Mengapa?

Sebuah komentar baris demi baris tidak masuk akal, tapi inilah yang saya tanyakan: mengapa Anda menginginkan ini?

Apakah karena ...

  • Anda ingin pemahaman lengkap tentang apa yang dilakukan perangkat lunak (belum tentu bagaimana)?
  • Anda ingin memastikan programmer lain dapat mengambil proyek jika saya pergi?
  • Anda ingin melihat bahwa saya sedang melakukan pekerjaan nyata?

Mungkin ada keinginan yang masuk akal di balik permintaan ini, dan Anda mungkin bisa membuat atasan Anda senang dengan mencari tahu dan memenuhi kebutuhan itu.

Memperbarui

Berdasarkan Mikey'skomentar, mungkin saya menyatakan ini sedikit terlalu blak-blakan. Saya tidak bermaksud bahwa Anda harus benar-benar mengatakan "mengapa Anda menginginkan ini?", Hanya saja Anda harus mengetahuinya . Tulisan dan nada suara membuat perbedaan besar. Secara khusus, Anda bisa mengatakan sesuatu seperti:

"Aku sudah memikirkan permintaanmu untuk memiliki penjelasan tentang setiap baris kode. Agak aneh melakukan hal-hal seperti itu. Aku bertanya-tanya apakah mungkin ada sesuatu yang tidak aku komunikasikan dengan baik kepadamu tentang pekerjaanku. Apa yang benar-benar ingin Anda pahami tentang kode kami, atau tentang apa yang saya lakukan? Apa yang ingin Anda capai di sini? "

Tentu saja itu mungkin bos Anda sama sekali tidak masuk akal. Tetapi kemungkinan besar dia tidak tahu seberapa aneh permintaan ini dan memiliki beberapa tujuan rasional dalam pikirannya.

Jika tidak, mulailah memoles resume Anda. :)


-1 untuk jawaban ini: Jika Anda ingin mempertahankan pekerjaan Anda (atau setidaknya meninggalkannya secara sukarela) Anda tidak boleh bertanya kepada bos seperti itu 'mengapa'? Ini adalah sesuatu yang harus dipikirkan, seperti yang disarankan orang lain.
Vektor

3
Saya tidak setuju dengan komentar Mikey. Mengikuti perintah secara buta adalah bodoh. Bertanya 'mengapa?' pada setiap permintaan telah menyelamatkan saya berjam-jam dari pekerjaan yang tidak perlu dan menghemat banyak uang perusahaan saya dalam proses. Ini disebut konsultasi, dan mereka yang tidak takut pada bos mereka melakukannya secara bebas dan memberi dampak besar. Ketika orang-orang yang bekerja untuk saya menyarankan sesuatu, saya juga bertanya kepada mereka 'mengapa?' demikian juga. Dalam kedua kasus, itu mencari pembenaran, dan itu bisa diterima untuk melakukannya.
Soviut

10

Kedengarannya seperti peluang bagus untuk mencoba pemrograman melek. Google itu. :)

Tapi ... itu belum tentu permintaan yang sepenuhnya tidak masuk akal. Bagian dari pekerjaan Anda (bagian yang lebih penting, imo) adalah untuk mengkomunikasikan algoritme Anda kepada pengembang lain, dan, jika perlu, orang-orang non-teknis. Programmer jenius soliter yang tidak bisa berkomunikasi selalu bermasalah, saya pikir.

Untuk itu, kode Anda harus sangat jelas (artinya: benar-benar mendokumentasikan diri sendiri atau didokumentasikan dengan baik, dan dengan "mendokumentasikan diri sendiri" maksud saya variabel dan fungsi memiliki satu makna atau tanggung jawab dan nama mereka mencerminkannya dengan jelas). Bos Anda mungkin punya alasan bagus untuk permintaannya. Mungkin (saya hanya menebak-nebak di sini) Anda atau pendahulu Anda memiliki reputasi untuk kode yang tidak dapat ditembus dan rapuh dan ini adalah obat atasan Anda. Ini agak ekstrem, tetapi mungkin latihan yang berguna untuk Anda. Saya berasumsi dia tahu bahwa perlu waktu untuk menulis dokumen yang lebih baik (dan jika tidak, dia harus dididik - itu seperti menulis makalah: butuh waktu lebih lama untuk menulis daripada membaca).


Saya telah melihat halaman Wikipedia. Itu mengingatkan saya pada "terstruktur <masukkan bahasa manusia di sini>" yang saya lihat selama studi. Anda menggunakan bahasa manusia untuk merepresentasikan struktur pemrograman baris demi baris dengan ekspresi seperti if blah then add 1 to xsebagai alternatif untuk nassi-schneiderman atau diagram alur. Apakah ini yang dimaksud dengan pemrograman melek huruf?
James P.

Anda satu-satunya di halaman ini, yang menyebutkan program melek huruf Knuth - membuat saya bertanya-tanya di bawah batu apa sisa poster hidup selama empat puluh tahun terakhir ...
cji

@ James: beli salinan "Tex - program" Knuth dan baca. Ini adalah pemrograman melek.
cji

10

Bahkan terjemahan baris demi baris tidak akan secara efektif menyampaikan makna setiap baris kode. Pemahaman pemrogram tentang sebaris kode selalu dalam konteks banyak faktor. Masuk ke sesuatu seperti sepotong kode multi-threaded dan terjemahan bahasa Inggris tidak akan lebih masuk akal daripada kode mentah. Pikirkan tentang fungsionalitas yang tersebar di antara beberapa fungsi / file. Beberapa kode sama sekali tidak masuk akal tanpa menjelaskan sejumlah besar kode lainnya. Cobalah untuk menjelaskan berbagai bagian yang terlibat dalam injeksi ketergantungan "baris demi baris" dan Anda akan melihat apa yang saya maksud. Hampir semua hal yang melampaui kode prosedural fungsi Tuhan akan membutuhkan pengetahuan pemrograman yang luas hanya untuk memahami terjemahan bahasa Inggris. Juga, lihat sesuatu yang sederhana seperti pernyataan keputusan if / else. Tidak ada baris demi baris, karena baris berikutnya tergantung pada data run time. Baris berikutnya bisa menjadi salah satu dari beberapa kemungkinan.Pada saat Anda menjelaskan apa yang dilakukan aplikasi Anda, Anda akan membuat PM Anda menjadi seorang programmer dan Anda berdua akan 5 tahun lebih tua.


10

Karena saya dulu mengajar pemrograman, saya akan sangat senang untuk mencobanya.

Dia akan dengan cepat mengetahui bahwa dia mendapatkan lebih dari yang ditawar, yang akan membuat saya sedih karena saya suka menjelaskan hal-hal :-)


3
Saya pikir ini adalah jawaban terbaik di sini. Saya tidak mengerti semua keengganan untuk mencobanya, maksud saya Anda akan dibayar untuk duduk di sana dan menjelaskan kode Anda! Sial, kecuali kode Anda benar-benar omong kosong, Anda mungkin akan menikmatinya, dan betapapun baiknya Anda mungkin akan menemukan beberapa bug dan tempat untuk perbaikan.
Bill K

1
Saya punya guru yang menjelaskan hal-hal saat mengetik kode yang ditampilkan melalui proyektor. Mungkin ini bisa dilakukan seperti pelajaran mengemudi. Jika Anda tidak dapat melewati semua kode setidaknya Anda dapat memberikan pengertian yang lebih baik tentang apa yang sedang dilakukan dan bagaimana caranya.
James P.

1
Saya mencoba masuk ke bisnis pengajaran sendiri, dan saya memberikan jawaban yang sama. Saya dengan @Bill, saya benar-benar kecewa bahwa orang akan mengambil sikap tertutup seperti itu. Apakah kita salah karena percaya bahwa ada baiknya menghabiskan waktu menjelaskan bahkan hanya sebagian kecil dari kode?
Rei Miyasaka

1
@Rei: Sikap, buruk atau baik, cenderung untuk mengambil alih sebagian besar orang yang serupa. Saya sudah memiliki banyak pengalaman (insinyur, mahasiswa pascasarjana, profesor, konsultan, karyawan jangka panjang) jadi saya suka berpikir yang memberikan perspektif. Juga, sikap saya telah berubah selama bertahun-tahun.
Mike Dunlavey

10

Ketika Anda merujuk ke 'Bos' Anda apakah ini "manajer menengah yang bertanggung jawab atas Anda / tim Anda"? atau Pemilik Perusahaan Anda? Apakah Anda dibayar "per jam" atau "dengan gaji"?

JIKA bos Anda adalah manajer tingkat menengah yang bertanggung jawab, BICARA DENGAN BOSS-NYA, tunjukkan bahwa untuk memenuhi persyaratan bos Anda, produktivitas Anda bagi perusahaan akan dikurangi menjadi 1/3 dari apa yang seharusnya.

JIKA atasan Anda adalah "orang yang menandatangani cek" jelaskan kepadanya hal yang sama, hanya secara diplomatis. Pekerjaan Anda telah berubah dari "Tulis kode" menjadi "Tulis kode, tulis penjelasan kode, jelaskan penjelasannya."

masukkan deskripsi gambar di sini


Mengapa tidak melakukannya dan mengambil uangnya? Apakah Anda begitu yakin bahwa satu-satunya nilai Anda suka memproduksi kode seperti monyet?
Bill K

9

Bagan alur mungkin akan lebih bermanfaat baginya. Ini tentu saja permintaan yang tidak biasa dan tidak banyak bicara tentangnya sebagai manajer.


18
Sebenarnya, itu memberitahuku banyak hal tentang orang ini ...
Marjan Venema

5
Itulah yang "tidak banyak bicara tentang" artinya dalam konteks ini - ia mengatakan banyak, memang, tetapi itu tidak menunjukkan banyak hal baik tentang individu.
Joseph Weissman

8

Fakta bahwa bos Anda rela meluangkan waktu untuk memahami kode yang Anda tulis, dapat Anda gunakan untuk keuntungan Anda. Coba perkenalkan dia dengan Mentimun: http://cukes.info/

dan buat bos Anda menulis tes BDD untuk Anda di masa depan.


Saya sudah mencoba membuat Mentimun digunakan di toko saya untuk sementara waktu ... sayangnya, (atau mungkin untungnya!) Bos saya tidak peduli apa yang terjadi di balik layar, asalkan berhasil. Hanya membuatnya mengerti manfaat dari menulis tes pertama adalah perjuangan berat.
Jason Lewis

6

Dia seharusnya tidak repot-repot mengetahui hal itu. Katakan padanya, bahwa dalam implementasi pengembangan perangkat lunak dapat berubah. Desain acara dapat berubah. Ceritakan kepadanya tentang penyembunyian informasi, enkapsulasi, dan abstraksi.
Dia, sebagai bagian dari tim Anda, sebagai klien kode Anda, dalam arti yang lebih luas, hanya boleh bekerja dengan abstraksi tingkat tinggi yang jelas tentang apa yang kode Anda lakukan. Cara yang sama setiap lapisan kode Anda bekerja dengan lapisan kode orang lain. Mengetahui lebih dari itu, hanya akan memperlambatnya, dan berisiko dia membuat asumsi berdasarkan cara kerja kode Anda. Asumsi-asumsi itu akan berhenti berlaku, ketika Anda harus mengubah kode Anda, yang menjadi masalah, jika dia membangun segala jenis sistem atau proses berdasarkan pada mereka.
Dan juga harus melakukan pekerjaan semacam ini akan mengurangi efisiensi Anda. Anda tidak hanya akan harus membuat perubahan berikutnya di dua tempat yang berbeda, tetapi juga akan berdampak negatif terhadap semangat kerja Anda, yang akan mengurangi hasil Anda lebih jauh.


6

Keindahan bahasa Inggris adalah yang mengaburkan dengan indah. Jika Anda menggunakan ini untuk keuntungan Anda, Anda mungkin tidak akan pernah berurusan dengan permintaan semacam ini lagi. Saya akan mengambil sepotong kecil kode sebagai sampel tetapi salah satu yang sangat abstrak dan sama sekali tidak mudah dimengerti. Saya kemudian akan menulis komentar dalam bahasa Inggris teknis seolah-olah Anda menulisnya untuk bab dalam buku pemrograman. Semakin lama dan semakin rumit untuk diikuti, semakin baik. Katakan padanya berapa jam Anda untuk mendokumentasikan fitur yang satu ini. Kemudian jelaskan bahwa itu hanya 1/10 dari 1% (gunakan angka aktual berdasarkan garis kode jika Anda bisa, mereka mungkin lebih buruk dari ini) dari basis kode yang sebenarnya. Ketika dia menyadari bahwa dia tidak tahu apa yang dikatakan terjemahan bahasa Inggris dan bahwa akan dibutuhkan 20.000 jam kerja untuk melakukan dokumentasi tingkat ini, dia akan mundur dengan cukup cepat. Tetapi dengan sungguh-sungguh berusaha menyelesaikan tugasnya. Jangan coba ini jika Anda tidak bisa melakukannya dan dia curiga Anda mempermainkannya.


6

Ini terlihat seperti kandidat untuk strip Dilbert -liburan-runcing-isu-liburan khusus ! Permintaannya tentu tidak terdengar masuk akal pada pandangan pertama.

Singkirkan humor, cobalah cari tahu apa yang sebenarnya dia butuhkan, dan mengapa, lalu beri tahu dia berapa biayanya dalam dolar atau jam untuk memberinya, dan biarkan dia memutuskan apakah dia ingin menghabiskan banyak uang untuk itu.

Sedangkan untuk Anda sendiri, hitung jam yang dibutuhkan untuk memenuhi permintaannya yang tampaknya aneh dan kemudian tentukan apakah Anda tidak akan lebih baik menginvestasikan sebagian kecil dari jumlah waktu itu dalam mencari pekerjaan baru yang bekerja untuk pemberi kerja yang bersedia memperlakukan Anda. sebagai seorang profesional!


1
Analisis biaya-manfaat harus melakukan pekerjaan itu. Mungkin manajer memiliki beberapa manfaat tambahan untuk dibawa masuk. Jika tidak berhasil, sulit untuk menegakkan dan membela manajemen tingkat atas.
mbx

6

Bawa dia ke kantor Anda dan beri dia tur kode Anda.

Dia akan menyadari bahwa dia membuat permintaan yang tidak masuk akal, dan dia akan pergi dan tidak pernah mengganggumu lagi.

Jika Anda tidak mengalah pada tuntutannya untuk membantunya mencoba memahami kode Anda, dia akan menemukan cara yang berbeda tetapi tidak masuk akal untuk menyodok Anda.

Ini adalah kasus di mana peredaan bekerja lebih baik daripada abrasi.


+1 - Saya berpikir di jalur yang sama - membawanya atas permintaan - dia kemungkinan akan bosan dan / atau takut mati sebelum terlalu lama ...
Vektor

+1 Saya suka itu - "bekerja lebih baik daripada abrasi".
Mike Dunlavey

6

Akan sangat baik jika kita memiliki penerjemah "Bahasa X ke Bahasa Inggris" yang melakukan ini. Kemudian seseorang dapat tersenyum dan berkata, tidak masalah, bos, Anda akan mendapatkannya sebentar lagi. Dan kemudian muncul surat dengan beberapa megabita teks yang berbunyi:

  • Biarkan a menjadi integer array baru dengan 20 elemen.
  • Biarkan x menjadi variabel untuk menyimpan bilangan bulat.
  • Set x ke 0
  • Sementara x lebih kecil dari 20 lakukan apa yang ditentukan dalam 2 baris berikutnya
  • atur elemen array a dengan indeks x ke hasil memanggil nThPrime dengan argumen x + 1
  • naikkan x sebanyak 1
  • ....

Pilihan lain adalah menyarankan pemrograman di Shakespeare untuk selanjutnya.


Saya akan membuat saran yang sama. Bos tidak menginginkan gambaran konseptual, ia menginginkannya baris demi baris sehingga harus memungkinkan untuk melakukan sesuatu dalam sehari atau lebih sehingga menciptakan dokumentasi yang sama sekali tidak berguna tetapi benar secara dangkal. Tidak masalah jika itu adalah sarang tikus if-elses di perl yang mudah dikacaukan oleh kasus sudut, itu hanya akan mengidentifikasi deklarasi variabel, modifikasi terhadap variabel, pemanggilan metode dll (ingat bahwa itu baris demi baris, tidak dalam cara groks kode).
PhilDin

Ya, bos ini tidak tahu apa-apa. Dia tidak tahu apa "abstraksi" itu, dia tidak tahu bahwa bahasa Inggris tidak baik untuk mengekspresikan program komputer, dia tidak bisa membayangkan bahwa dia benar-benar tidak ingin mengetahui semua detail itu, itu sebabnya dia membayar seorang programmer. Karena itu, ia layak mendapat pelajaran seperti ini.
Ingo

5

Bos saya menginginkan penjelasan bahasa Inggris baris demi baris dari kode kami

Sulit.

Karena dia bukan seorang programmer, dia tidak bisa mengikuti kode, jadi ingin semuanya diterjemahkan ke dalam bahasa Inggris.

Jika dia bukan seorang programmer, dia seharusnya tidak membaca kode. Sama sekali.

Sebaliknya, berikan dokumentasi tingkat tinggi.

Ini bukan permintaan yang masuk akal, bukan?

Tidak.


4

Sebagai seorang programmer, Anda benar-benar memiliki pekerjaan "dua".

Yang pertama adalah membuat program yang bagus. Yang kedua adalah "menjual" mereka kepada pelanggan di dalam dan di luar perusahaan.

Permintaan bos Anda "menyakiti" pekerjaan pertama Anda. Membutuhkan lebih banyak waktu untuk mendokumentasikan program Anda. Di sisi lain, dia sebenarnya membuat Anda bekerja lebih keras pada pekerjaan "kedua" Anda.

Bos Anda meminta Anda untuk mendokumentasikan program Anda dalam bahasa Inggris untuk manfaat NYA, dan mungkin untuk kepentingan orang-orang yang harus berurusan dengannya, di dalam dan di luar perusahaan. Jika Anda membantunya melakukan pekerjaannya, itu akan bermanfaat bagi Anda dalam jangka panjang, ketika Anda meminta lebih banyak perangkat keras, personel, atau uang untuk kenaikan gaji. Bagaimanapun, dia meminta Anda untuk melakukan lebih banyak pekerjaan.


3
Mendokumentasikan baris demi baris! = Menjual proyek. Seharusnya sudah ada dokumen yang menyediakan informasi ini, itu disebut persyaratan. Saya setuju dengan 2 deskripsi pekerjaan Anda, tetapi mendokumentasikan ke tingkat itu tidak akan bermanfaat untuk menjual proyek / sistem / aplikasi. Ada tingkat dokumentasi yang sesuai untuk mempresentasikan karya Anda, dan ini bukan.
cdkMoose

Saya berani bertaruh orang yang menulis cek di perusahaan ini tidak akan senang manajer ini menghabiskan banyak sumber daya perusahaan.
JeffO

@ Jeff O: Bisa jadi. Atau bisa jadi perusahaan WHOLE seperti ini, sampai ke puncak.
Tom Au

4

Saya pikir BDD akan cocok dengan masalah ini, meskipun tampaknya proyek Anda hampir selesai, jadi agak sulit untuk mengimplementasikannya sekarang, jadi itu lebih seperti untuk referensi di masa mendatang.

Dengan penggunaan BDD-kasus digambarkan sebagai dokumen yang dapat dibaca secara manusia yang kemudian diterjemahkan ke dalam tes fungsional otomatis.


Ini mungkin saran yang paling konstruktif sejauh ini. Pengembangan yang didorong oleh perilaku dirancang untuk memenuhi kebutuhan ini: untuk membantu programmer dan manajer / klien mereka sepakat tentang apa yang dilakukan perangkat lunak. Menulis deskripsi membantu dengan perencanaan kode, dan menjalankan tes membuktikan bahwa mereka masih deskripsi yang akurat.
Nathan Long

4

Mungkin, permintaan ini adalah saat yang tepat untuk mempelajari hal-hal seperti ANTLR . Ambil ANTLR, ambil tata bahasa Anda, parsing semua kode yang Anda miliki, lintasi AST Anda yang menghasilkan deskripsi berbasis template untuk setiap node, demikian i++dideskripsikan sebagai increase i by 1 using postfix increment operator. Itu pasti sangat lucu. Bos Anda mungkin juga ingin alat ini dimasukkan ke skrip build, jadi setiap kali Anda melakukan perubahan, ia akan menerima email ~ 20 MB yang menjelaskan apa yang versi baru lakukan.

PS Hanya bercanda, dia idiot.


3

Meskipun saya setuju bahwa ini adalah permintaan yang tidak masuk akal, bos Anda mungkin menghargai sesuatu seperti hasil Docco , yang memisahkan kode Anda dan komentar baris-demi-baris atau klausa demi klausa menjadi output HTML dua kolom, dengan kode pada satu sisi dan prosa di sisi lain. Anda harus mengetik komentar sendiri, tentu saja, tetapi presentasi IMHO agak bagus, bahkan untuk pembaca non-teknis. Lihat, misalnya, bagian berkomentar baris demi baris dari kode beranotasi untuk Underscore.js . Ada juga versi skrip Python dan shell.


Ini adalah salah satu jawaban paling berguna yang telah saya lihat untuk pertanyaan itu. Saya memang benar-benar mencoba menggunakan docco, tetapi ternyata ada masalah dengan beberapa komentar saya yang ada, dan salah mengartikannya. Karena itu saya pergi dengan JSDoc, dan mengikuti pedoman google untuk menghasilkan dokumentasi. Tidak secantik, tetapi sangat lengkap, dan juga format standar. Masalahnya dengan docco bagi saya adalah Anda perlu menyusun kode Anda agar sesuai dengan komentar, atau itu tidak masuk akal. Terima kasih untuk sarannya.
Billy Moon

3

Mungkin saja atasan Anda tidak tahu dan terintimidasi, tetapi sebenarnya orang yang berakal. Jika demikian, berunding dengannya mungkin berhasil - percakapan santai di mana Anda berjanji untuk memberikan "apa yang sebenarnya ia inginkan" yaitu; panduan prosa tentang apa yang sedang dilakukan program.

Jika turun ke "jalan saya atau jalan raya" lebih baik periksa gas Anda sekarang.


3

Anda dapat menulis beberapa tes penerimaan menggunakan kerangka kerja yang didorong oleh perilaku seperti mentimun ? Itu tidak akan menjelaskan kode; itu akan menjelaskan apa yang dilakukannya, dan dalam bahasa alami. Ini juga memiliki keuntungan sebagai executable, sehingga Anda selalu dapat memastikan bahwa dokumentasi tersebut mutakhir, karena jika tidak, pelari uji akan berwarna merah.

Lihat video intro. Mungkin ini pengalihan yang bagus saat Anda menemukan bos baru ... ;-)


2

Manajer Anda hampir pasti tertekan oleh kenyataan bahwa ia tidak mengerti apa yang dilakukan orang-orang yang ia kelola, dan ia tidak memiliki latar belakang untuk memahami hasil yang mereka hasilkan.

Aku ragu dia memikirkan solusi ini dengan sangat teliti, dan mungkin tampak masuk akal baginya pada pandangan pertama. Tapi itu terutama karena dia tidak mengerti apa kode pemrograman sebenarnya.

Setiap programmer mengerti absurditas permintaan ini, tetapi kami melakukannya karena kami secara intuitif tahu bahwa setelah Anda melewati bahasa, semua yang diungkapkan adalah algoritma, yang sama-sama samar.

// Set s to the first address in the server list
server_info *s = cmd->servers;
// Loop until s is NULL
while (s) {
    // call the server's init function passing our current ID and address
    s->init(proc->id,*addr);
    // call log::info with our custom message
    log::info("Starting server %s",s->name);
    // Set s to the value returned by the server's next() function
    s=s->next();
} // end of loop

Masalahnya di sini adalah bahwa sementara komentar menjelaskan apa yang dilakukan setiap baris, Anda masih tidak tahu apa kode sebenarnya kecuali Anda memahami apa semua implikasinya. Sudah jelas jika Anda seorang programmer dan telah melihat pola ini sebelumnya; tetapi tunjukkan ini kepada seseorang yang hanya memahami penjualan, dan dia akan menjadi sama bingungnya setelah membaca komentar seperti sebelumnya.

Anda sebenarnya dapat menghemat waktu dengan mengajari atasan Anda beberapa pemrograman dasar. Jika dia ingin membaca kode Anda, berikan dia alat untuk dapat melakukannya. Kebanyakan bahasa sintaksisnya cukup kompak, dan mempelajari strukturnya hanya membutuhkan satu atau dua jam. Dia hampir pasti akan menyerah setelah beberapa hari, tetapi setidaknya dia akan tahu apa yang dia sampaikan, dan yang lebih penting mengapa dia tidak ingin membaca kode Anda.


1

IMHO ... jika dia bertanggung jawab untuk menyelesaikan tugas, dia harus tahu cara kerjanya ... :)


2
Apakah Anda merujuk kepada manajer atau programmer?
Nathan Long

Berapa banyak perusahaan yang mampu membuat setiap manajer non-teknis menghabiskan banyak waktu pengembang ini?
JeffO
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.