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

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.

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.

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

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?

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?

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.

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

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

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.

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.

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

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

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.

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

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

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

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.

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.

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.

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!

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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