Klien saya ingin 25% komentar di proyek saya saat ini, bagaimana bereaksi? [Tutup]


96

pengembang junior di sini.

Saat ini saya bekerja sendiri di aplikasi web untuk klien besar perusahaan saya. Saya mulai bulan lalu. Klien menginginkan setidaknya 25% komentar di setiap proyek perangkat lunaknya.

Saya memeriksa kode aplikasi sebelumnya dan berikut adalah pengamatan saya:

  • setiap file dimulai dengan blok komentar (paket, tanggal terakhir diperbarui, nama perusahaan saya & hak cipta)
  • semua variabel diberi komentar dengan namanya // nameOfCustomer public String nameOfCustomer

  • semua getter dan setter dikomentari

  • sangat sedikit komentar yang bermanfaat

Sepertinya pengembang hanya memberikan komentar sebanyak mungkin untuk mencapai ambang 25% itu, terlepas dari kualitas dan kegunaannya. Perusahaan saya memberi tahu saya bahwa "kami melakukannya sesuai keinginan klien".

Saya tidak berbicara langsung dengan klien tentang hal ini. Inilah argumen saya sejauh ini:

  • baris tidak berguna untuk membaca dan menulis (buang-buang waktu)
  • komentar terkadang tidak diperbarui (sumber kebingungan)
  • pengembang cenderung menggunakan atau memercayai komentar yang sangat berguna

Apa saran Anda tentang hal ini? Bagaimana saya harus menangani situasi ini?


162
Itu konyol. Namun, jika itu yang diinginkan klien dan klien membayar Anda banyak uang untuk mendapatkannya, maka itulah yang Anda berikan kepadanya.
Robert Harvey

20
25% dari baris (artinya Anda tidak pernah memberikan komentar pada baris yang sama dengan kode) atau 25% dari byte ?
RonJohn


10
Lebih baik hati-hati di sini. Biasanya ada alasan di balik ekspektasi semacam ini ... Jika Anda memberi tahu pelanggan bahwa komentar itu tidak berguna, ia mungkin masih menginginkan 25% komentar (dengan alasan apa pun yang mereka miliki) tetapi sekarang TANPA yang Anda sebut tidak berguna .. Anda mungkin menemukan diri Anda dalam lebih banyak masalah .... Kadang-kadang argumen pelanggan dibuat terlalu jauh sehingga membingungkan Anda ... Hanya berbicara dari pengalaman
user1841243

19
Ini adalah objek pelajaran dalam aturan bahwa Anda akan memiliki banyak kesempatan untuk mengamati dalam karir Anda: hal yang Anda ukur adalah hal yang Anda dapatkan . Anda telah diberikan metrik untuk komentar, dan oleh karena itu komentar adalah hal yang akan Anda dapatkan. Pelanggan yang lebih masuk akal akan memberi Anda metrik untuk kinerja, kebenaran, ketahanan, dan biaya, dan kemudian Anda akan mendapatkan hal-hal itu. Tetapi Anda tidak memiliki klien yang masuk akal.
Eric Lippert

Jawaban:


115

Semua jawaban dan komentar lain di sini benar-benar membuat saya marah, karena mereka sangat bertentangan dengan reaksi pertama saya dan juga bertentangan dengan sikap yang saya saksikan pada rekan kerja saya. Jadi saya ingin menggambarkan pendekatan alternatif, jika hanya demi menjadi suara yang berbeda pendapat .

Prinsip penuntun jawaban ini adalah, "Menyenangkan pelanggan". Menyenangkan pelanggan tidak hanya berarti memenuhi harapan mereka; itu berarti memahami permintaan mereka begitu dalam sehingga Anda dapat menafsirkan apa yang mereka katakan dengan cara mereka bersungguh-sungguh, dan memenuhi apa yang mereka minta. Jawaban lain tampaknya dipandu oleh prinsip kepatuhan jahat, yang menurut saya membenci; dan selain itu adalah praktik bisnis yang dipertanyakan karena ini cara yang buruk untuk mendapatkan pelanggan tetap.

Bagi saya, ketika saya mendengar klien berkata, "Saya ingin 25% komentar", itu adalah awal dari sebuah dialog. Bagi saya jelas bahwa implikasinya di sini adalah "Saya ingin banyak teks deskriptif, sehingga pendatang baru untuk basis kode ini dapat bangun dan berjalan dengan cepat", bukan "Saya ingin Anda menambahkan keacakan dalam kategori sintaksis tertentu" sebagai jawaban lain tampaknya mengambilnya. Dan saya akan menanggapi permintaan itu dengan serius, dan bermaksud untuk menulis banyak komentar yang deskriptif dan membantu, membimbing pendatang baru ke struktur kode, menunjukkan keputusan rekayasa yang mengejutkan dan menguraikan alasan yang masuk ke dalamnya, dan memberikan bahasa Inggris tingkat tinggi deskripsi bagian kode yang rumit (bahkan jika mereka tidak memiliki kejutan). Niat dan pengertian ini adalah titik awaldiskusi - itu bahkan sebelum kita mulai berbicara. Bagi saya implikasi dari permintaan itu begitu jelas sehingga bahkan tidak perlu klarifikasi itu; tetapi jika bagi Anda tidak jelas Anda tentu harus memeriksa dengan mereka!

Oke, jadi ke mana dialognya kalau itu titik awal? Bagian selanjutnya dari dialog seperti ini:

  1. Saya berharap ini menjadi upaya tambahan yang serius, mungkin dalam fase kedua proyek, yang berada di atas dan di luar produksi alat yang mereka pedulikan bekerja. Mungkin perlu beberapa menit diskusi untuk membahas proses ini dan mengapa ini merupakan pekerjaan tambahan, tetapi saya akan mengabaikannya di sini karena sebagai programmer profesional saya berharap Anda tahu betapa sulitnya membuat komentar yang baik.
  2. "Upaya tambahan yang serius" berarti kita mungkin memerlukan anggaran waktu yang lebih lama dan anggaran moneter yang lebih besar; atau kita mungkin perlu mengurangi anggaran fitur; ataukita mungkin perlu berkompromi pada kualitas dan kuantitas komentar. Bagian ini akan menjadi sedikit negosiasi. Tetapi menurut pendapat saya, Anda harus sangat di muka tentang biaya melakukan pekerjaan tambahan ini, dan memastikan bahwa itu adalah fitur yang penting bagi klien sehingga mereka bersedia menanggung biaya ini. Dan jika mereka - hebat! Anda mendapatkan waktu dan uang ekstra, dan mereka mendapatkan komentar berkualitas tinggi. Semua orang menang. Dan jika ternyata fitur komentar tidak begitu penting bagi mereka sehingga mereka rela kehilangan kemampuan untuk mengacaukan widget atau bersedia membiarkan tenggat waktu lewat hingga akhir Granuary, 20x6, maka semua orang menang lagi: mereka mendapatkan produk yang mereka inginkan. inginkan, dan Anda tidak perlu menghabiskan usaha ekstra yang diperlukan untuk membuat komentar berkualitas tinggi.

Di sinilah saya pikir dialog tidak boleh pergi:

  1. Jangan mengancam klien dengan komentar berkualitas rendah. Biarkan mereka membantu Anda memilih tingkat upaya yang ingin mereka keluarkan dan bahwa mereka bersedia membayar. Jangan menjanjikan mereka 25% komentar dan kemudian memberi tahu mereka bahwa Anda berniat untuk memenuhi janji ini dengan autogenerating keacakan setelah proyek dibangun.
  2. Jangan sembunyikan rencana Anda. Jangan menjanjikan mereka 25% komentar, dan kemudian secara otomatis membangkitkan keacakan tanpa memberi tahu mereka bahwa itulah yang akan Anda lakukan. Ketika mereka memperhatikan (bukan jika), Anda berdua kehilangan banyak waktu: mereka tidak senang dengan produk yang mereka dapatkan, dan Anda mendapatkan kata-kata negatif dari mulut ke mulut.
  3. Jangan mencoba meyakinkan mereka bahwa mereka tidak ingin komentar. Mereka jelas menginginkan komentar. Diskusikan pertukaran dari berbagai pendekatan: ya! Diskusikan cara-cara alternatif untuk membuat pendatang baru yang ramah basis kode: ya! Katakan pada mereka bahwa mereka tidak tahu apa yang mereka inginkan: eh, tidak. Anda ingin bekerja dengan mereka untuk mendapatkan apa yang mereka inginkan; jadi pahami apa itu dan cari tahu cara terbaik untuk memberikan itu kepada mereka dalam anggaran yang mereka setujui, memprioritaskan fitur yang paling mereka pedulikan jika sumber daya yang mereka miliki tidak mencukupi.
  4. Jangan membuat alasan tentang seberapa sulit komentar untuk ditulis. Menulis kode itu sulit; kode debug sulit; menulis komentar itu sulit. Jika mudah, mereka tidak akan mempekerjakan Anda. Lewati saja keluhan dan langsung ke titik yang mereka pedulikan, yaitu bagaimana upaya ekstra yang diperlukan mempengaruhi mereka.

3

9
@ ThorstenS. Perusahaan tempat saya bekerja melakukan supermajority dari pekerjaannya untuk industri pertahanan. Mungkin ingin memeriksakan kekuatan psikis Anda. Juga, saya tidak pernah mengatakan "jangan menginterpretasikan keinginan mereka bagaimana mereka menulisnya": Saya akan memperlakukan "25% komentar" sebagai permintaan serius tapi insidental - permintaan sebenarnya adalah "badan besar penulisan teknis", dan 25% adalah hanya sebuah indikasi tentang tingkat upaya yang mereka harapkan untuk masuk ke dalam tubuh itu, mungkin pada dasarnya dipilih secara sewenang-wenang, namun demikian target yang tidak boleh Anda lewatkan.
Daniel Wagner

12
Jika saya menyewa seorang programmer, Mr. Daniel Wagner adalah tipe orang yang ingin saya pekerjakan.
Joe Gayetty

5
Ini adalah jawaban yang bagus karena berusaha mengidentifikasi dan mengatasi maksud dari permintaan yang bertentangan dengan surat permintaan. IMO Ini adalah perbedaan antara pengembang dan seseorang yang baru saja menulis kode.
Justin Ohms

6
Sebaiknya jelaskan bahwa komentar ini akan menambah biaya perawatan . Setelah dibuat, mereka harus terus diperbarui , atau mereka membuang-buang waktu dan uang. (Menunggu hingga besok hingga +1 sehingga Anda benar-benar mendapatkan rep.;) Anda layak mendapatkannya.)
jpmc26

83

Pelanggan adalah raja. Jadi sebagai kontraktor Anda harus memenuhi apa pun yang telah ditetapkan klien sebagai standar kualitas. Atau Anda berisiko keluar.

Ini dikatakan, sangat penting bagaimana standar kualitas (di sini buruk) didefinisikan:

  • Standar kualitas kontraktual: kode yang dikirimkan harus mematuhi, atau jika tidak, ini merupakan pelanggaran kontrak. Tidak ada pilihan.

  • Standar kualitas perusahaan formal: bahkan jika itu bekerja dengan sempurna, kode yang tidak mematuhi akan dianggap kualitas buruk oleh begitu banyak orang, sehingga Anda akan menjadi tua sebelum Anda mengubahnya menjadi praktik yang lebih baik. Lebih buruk: alat yang terkenal dapat digunakan untuk mengotomatisasi dan melegitimasi metrik kualitas semacam itu (misalnya, sonar cube ). Hampir tidak ada pilihan.

  • Kriteria ad-hoc ditentukan oleh beberapa orang di klien. Di sini Anda bisa berdiskusi. Ada harapan :-)

Dalam kasus terakhir ini, mungkin ada beberapa fleksibilitas, dan Anda dapat mencoba secara diplomatis untuk menyampaikan maksudnya. Berikut beberapa argumen yang bertentangan dengan kriteria pelanggan:

  • Masalah produktivitas: pengkodean dilakukan dua kali (sekali dalam bahasa Inggris dan sekali dalam kode).
  • Masalah akurasi: jika perubahan dilakukan dalam kode, mereka harus dilakukan dalam komentar, atau komentar mungkin menjadi tidak berguna.
  • Masalah refactoring: karena alat refactoring tidak memproses nama variabel dalam komentar.
  • Masalah risiko: ambiguitas (atau keusangan) komentar dapat menimbulkan kebingungan dan risiko untuk meningkatkan bug.
  • Kuantitas bukan kualitas
  • Kumpulan komentar lucu yang tidak berguna ini di StackOverflow .
  • Artikel ini yang berpendapat bahwa rasio komentar yang tinggi bahkan bisa menjadi tanda bau kode.

Tetapi alih-alih berbicara menentang yang buruk dan menghadapi pelanggan, mungkin Anda bisa mempromosikan pendekatan yang lebih baik:

  • Kode bersih (sarankan buku untuk pelanggan Anda: ada bagian yang meyakinkan yang didedikasikan untuk komentar dan kode dokumentasi diri).
  • Praktik dokumentasi: Hal-hal yang paling sulit untuk dipahami, dan karenanya informasi yang paling berharga, seperti misalnya hubungan dan interaksi antar kelas didokumentasikan dengan lebih baik dalam dokumen terpisah (misalnya dalam gambar UML daripada 1000 kata komentar?)

Jika pelanggan masih tidak yakin, Anda bisa mengusulkan alternatif eksperimental, menggunakan alat menghasilkan dokumentasi secara otomatis dengan komentar, seperti javadocatau doxygen. Usulkan untuk mengubah fokus dari kuantitas (25% dari kode) ke kualitas (menghasilkan javadoc dimengerti).


7
Jika pelanggan adalah raja, itu hanya menunjukkan betapa tidak efisiennya kerajaan pelanggan seperti itu!
Steve

82
" Pelanggan adalah raja. Jadi sebagai kontraktor Anda harus memenuhi apa pun yang telah ditetapkan klien sebagai standar kualitas. Atau Anda berisiko keluar. " Kebalikannya adalah pengalaman saya. Mereka yang memberi pelanggan apa yang mereka pikir diinginkan dan bukan apa yang sebenarnya mereka butuhkan tidak bertahan lama. Bahkan, saya hanya memesan bentuk pelecehan ini untuk klien masalah nyata - dan dosis kedua tidak pernah diperlukan.
David Schwartz

6
@ DavidSchwartz ya, tentu saja. Terkadang pelanggan berpikir mereka membutuhkan sesuatu tetapi benar-benar membutuhkan yang lain. Terserah konsultan atau pengembang untuk meyakinkan, dan 2/3 dari jawaban saya persis tentang ini. Tetapi itu semua tergantung pada konteks kontrak dan tingkat kepercayaan antara penyedia dan klien. Jadi aturan pelanggan adalah raja harus diingatkan (sebenarnya saya telah beberapa kali mengalami dengan pelanggan, bahwa setelah perdebatan panjang tentang solusi optimal, saya menaikkan kalimat ini dan yang memicu perubahan sikap tiba-tiba dan pertimbangan ulang argumen dengan hati-hati ;-) ).
Christophe

7
"Masalah akurasi: jika perubahan dilakukan dalam kode, mereka harus dilakukan dalam komentar, atau komentar mungkin menjadi tidak berguna." Saya akan mengatakan itu bahkan lebih buruk daripada tidak berguna . Sebuah komentar yang kedaluwarsa mungkin berubah menjadi bug (atau seseorang yang mengembalikannya karena mereka pikir itu bug) sangat cepat ketika Anda berharap itu menjadi sumber kebenaran dan memercayainya.
Hamatti

11
@ Hamatti Memang. Saya pernah menghabiskan banyak waktu untuk menguraikan maksud asli di balik kalimat yang berbunyi,i++; // count down
TKK

18

Klien menginginkan setidaknya 25% komentar di setiap proyek perangkat lunaknya.

Apakah klien benar-benar ingin 25% komentar atau apakah klien Anda ingin kode Anda sejelas mungkin?

IMHO, klien tahu apa yang dia inginkan, tetapi tidak apa yang dia butuhkan. Karena klien bukan pengembang itu sendiri dan mendapat umpan balik dari pekerja / pelanggannya sendiri, klien Anda hanya melihat bagian atas gunung es.

Saya kira klien Anda memiliki beberapa pseudo-knowledge dan ingin kode didokumentasikan dengan baik dan mudah dan murah dipelihara, dan alat untuk ini adalah komentar (dalam benaknya).

Cobalah berbicara dengannya dan siapkan beberapa cuplikan kode dengan kode yang ditulis dengan baik yang menjelaskan dirinya sendiri, dan satu lagi yang ditulis dengan komentar buruk. Hanya beberapa baris. Perlihatkan ini jika diperlukan dan gunakan sebagai gambar untuk kata-kata Anda.

Bicaralah dengan klien Anda / supervisor / apa pun dan cobalah untuk memberi tahu mereka prinsip-prinsip modern kontrol versi (tidak perlu komentar di awal file) dan kode bersih (saya merekomendasikan buku juga) dan dengan demikian menghasilkan kode yang menjelaskan diri.

Mungkin, jika Anda dapat menunjukkannya dengan cukup baik dan membuat klien Anda mengerti bahwa dia menginginkan kode bersih, bukan hanya komentar, Anda dan tim Anda dapat menulis kode yang lebih baik (dengan lebih sedikit komentar) dan segera menunjukkan bahwa Anda adalah pengembang yang baik yang patut dijaga .


13
Kode yang menjelaskan sendiri adalah prinsip yang menyenangkan. Sayangnya itu tidak bekerja dengan baik di dunia nyata. Antarmuka dan proses internal yang kompleks perlu didokumentasikan, dan hanya memilih nama yang bagus tidak cukup baik. Unit apa saja nilai-nilai itu? Faktor penskalaan? Tarif sampel? Kapan aman untuk memanggil metode itu, dan kapan bukan? Pengecualian apa yang dilemparkan untuk kondisi apa? Dan seterusnya, dan seterusnya. Inilah yang membuat kode Anda terpelihara. Dunia nyata memiliki kompleksitas yang tidak akan pernah diwakili oleh cuplikan kode, dan itulah sebabnya Anda perlu mendokumentasikannya dengan baik.
Graham

2
@ Graham Ya, komentar tidak sepenuhnya tidak dapat dihindari. Tetapi, komentar seperti kode: semakin banyak Anda membuat, semakin banyak yang perlu dipertahankan. Tetap ringkas membantu saya percaya.
Robert Dundon

Saya tidak ingin mengatakan bahwa beberapa hal sama sekali tidak berguna, tetapi komentar persis seperti nama fungsi atau variabel tidak berguna. Sedikit kode singkat harus menunjukkan bahwa itu mungkin tanpa komentar dan tidak boleh menegakkan lingkungan bebas komentar. Jika Anda ingin menunjukkan pengecualian apa yang dilemparkan atau menjelaskan fungsi lebih lanjut, Anda dapat menggunakan tag ringkasan untuk fungsi. Jika Anda ingin memberi sinyal dependensi, modelkan objek yang diperlukan sebagai parameter input, dll. Tidak ada cara sempurna untuk melakukan apa pun, dapatkan yang terbaik dari kedua dunia
Chrᴉz

@ Chriz Tentu saja, saya setuju. Jika komentar tidak menambahkan informasi, tinggalkan saja. Tetapi seperti yang saya katakan di balasan lain, persentase ini benar-benar hanya tes bau kode. Anda membenarkannya, auditor memeriksanya, semua orang bergerak. Kekhawatirannya adalah seseorang yang menganggap kode mereka benar-benar menjelaskan diri sendiri, dan belum memikirkan semua hal semacam itu.
Graham

12

Ini mengingatkan saya pada jawaban Stack Overflow konyol yang Anda lihat itu terdiri dari satu baris diikuti oleh, secara harfiah, "beberapa teks di sini untuk mencapai batas karakter minimum".

Ketika ini terjadi, argumen dapat dibuat bahwa dua kelompok orang yang bersalah:

  1. Orang-orang yang membatasi - jelas itu berlebihan dan mencegah orang mengirimkan informasi mereka yang benar tanpa menambahkan suara buatan

  2. Orang-orang yang mengirimkan informasi yang tidak terbentuk dengan benar, kemudian menambahkan suara buatan ketika sistem meminta mereka untuk menambahkan lebih banyak zat yang sebenarnya

Terkadang, sebuah pertanyaan akan sederhana dan sesuai topik, dan tidak ada banyak yang bisa dikatakan selain beberapa kata. Namun, ini sangat jarang. Dalam hampir semua kasus, ada banyak hal yang perlu dikatakan. Jika tidak ada yang lain, itu harus sangat jelas bahwa cara untuk mengatasi pembatasan karakter tidak hanya dengan membuang noise acak ke dalam posting Anda.

Situasi komentar yang Anda hadapi ini hampir sama. Pengembang Anda telah mengambil permintaan komentar, dan menerapkannya dengan memasukkan noise acak ke dalam kode mereka. Mendokumentasikan nama-nama variabel, tepat di sebelah deklarasi variabel, adalah vandalisme . Itu seharusnya tidak pernah terjadi.

"Tapi bagaimana lagi kita bisa mencapai 25%?" Dengan menulis komentar aktual tentang substansi. Gunakan lebih banyak kata, kata-kata yang lebih baik, kata-kata terbaik untuk mendokumentasikan efek fungsi. Perluas penjelasan Anda. Jelaskan kasus tepi secara lebih rinci.

Namun, kembali ke titik semula, klien juga sebagian bersalah di sini, karena "25% dari kode sumber" sangat sewenang-wenang. Namun, pada akhirnya, mereka adalah klien, jadi manfaatkan yang terbaik. Tapi maksud saya "terbaik". Bukan "terburuk", seperti yang telah terjadi sejauh ini.


5

Saya tidak tahu apa masalahnya dengan persyaratan ini.

Hanya dengan melakukan oksigenasi dasar kode Anda, Anda mungkin sudah mencapai 10% atau lebih. Dan mari kita ambil 5% lagi dari komentar yang telah Anda tulis sendiri (beberapa menulis lebih banyak, tetapi 5% sepertinya perkiraan konservatif jika Anda belum mengambil sumpah diam). Pada titik ini sekitar 15% (ya ya, saya tahu, 5% dari 90% kurang dari 5%, jangan rewel). Jika oksigen Anda kurang dari 10%, mungkin metode Anda sangat panjang; biasanya ide yang bagus untuk memecahnya menjadi yang lebih kecil (kebanyakan pribadi / terlindungi), atau menggunakan kelas pembantu yang lebih umum, dll.

Sekarang, untuk sisa teks komentar - masukkan pertimbangan desain dan skenario penggunaan di kelas / komentar tingkat file. Memiliki beberapa tabel atau ASCII-art (atau kode doxygen yang menghasilkan hal-hal yang tampak lebih bagus ketika dirender). Saya tidak tahu, tentu saja, tentang apa proyek Anda, tetapi saya yakin Anda dapat melakukan ini tanpa komentar palsu (selain pelat oksigen) dan mencapai sesuatu yang mendekati 25%.

Jika itu hanya, katakanlah, 20% dan bukan 25% - Saya yakin klien hanya memberikan nomor itu sebagai sesuatu yang sewenang-wenang, dan akan baik-baik saja dengan itu. Ngomong-ngomong, bicarakan dengan mereka untuk membahas apa yang harus dicakup oleh komentar; dan tunjukkan pada mereka contoh file komentar untuk melihat apakah mereka senang. Jika ya maka itu saja, jika mereka pikir ada sesuatu yang hilang mereka akan memberi tahu Anda apa yang hilang. Mereka tidak akan memberi tahu Anda "Kami tidak dapat menyarankan komentar tambahan yang mungkin tetapi kami masih ingin Anda menambahkan beberapa".

PS - Lihatlah kode kontainer Java standar untuk melihat bagaimana Anda dapat mencapai, oh, 70% atau lebih ...


5

Memiliki 25% komentar dalam kode Anda adalah tujuan yang sangat baik untuk dimiliki, dan itu membuat klien senang. Sekarang menulis 25% komentar pengisi jelek seperti "i + = 1; // naikkan saya dengan 1" harus ada di bawah Anda, jadi luangkan waktu Anda, tulis komentar yang bermanfaat, dan nikmati perasaan bahwa Anda sebenarnya dibayar untuk melakukan sesuatu yang harus Anda lakukan bagaimanapun.


Itu bagus juga +1. Saya tidak tahu apakah ada tujuan yang baik yang dinyatakan dalam tingkat komentar, tetapi mungkin banyak dari kita mencapai 'tujuan' ini dengan cara yang bermanfaat, tanpa mengetahui ... Saya baru-baru ini menemukan kembali sepotong kode lama yang saya tulis di tahun 80-an pada awal karir saya, dengan algoritma kinerja tinggi yang inovatif di dalamnya: ia hanya memiliki 10% dari komentar, tetapi secara surut, saya berharap saya telah menempatkan lebih banyak di dalamnya ;-)
Christophe

4

Kita semua tahu ini adalah persyaratan omong kosong. Pertanyaan menarik di sini adalah

bagaimana bereaksi?

Saya sangat percaya dalam membuat masalah terlihat. Di sini saya akan menggunakan fakta bahwa uang berbicara.

Minta saya untuk melakukan ini dan saya akan mengatakan yakin, itu akan menambahkan 1% ke tawaran saya. Oh, tapi itu akan menambah 20% ke tawaran pemeliharaan di masa depan.

Hanya sekali mereka bertanya mengapa saya akan mengajar mereka bahwa maksud dari nama baik adalah untuk menghindari perlunya berkomentar.

Sebagai alternatif, saya akan mengusulkan membuat dokumentasi yang bertujuan untuk mendapatkan pemrogram pemeliharaan dengan seperangkat kualifikasi yang diasumsikan untuk mempercepat ide-ide di balik proyek. Atau yakin, saya bisa memberi Anda 25% komentar. Terserah kamu.


3

Ya, saya mengerti frustrasi Anda dengan aturan konyol. Saya sudah membaca banyak program dengan komentar tidak berguna seperti

x = x + 1; // add 1 to x

Dan saya berkata pada diri saya sendiri, Jadi ITULAH arti tanda plus itu !! Wow, terima kasih sudah memberi tahu saya, saya tidak tahu itu.

Namun demikian, pelanggan membayar tagihan. Karena itu, Anda memberi mereka apa yang mereka inginkan. Jika saya bekerja di sebuah dealer mobil dan seorang pelanggan mengatakan dia menginginkan sebuah truk pickup, saya tidak akan berdebat dengannya tentang apakah dia benar-benar membutuhkan truk pickup dan menanyai dia tentang apa yang dia harapkan untuk diangkut. Saya akan menjualnya truk pickup.

Oke, ada saat-saat ketika apa yang diinginkan pelanggan dan apa yang benar-benar dia butuhkan begitu jauh sehingga saya mencoba membahas masalah itu dengannya, mungkin meyakinkannya untuk menyetujui sesuatu yang lebih rasional. Kadang ini berhasil, kadang tidak. Pada akhirnya, jika aku tidak bisa berubah pikiran, aku memberikan apa yang dia inginkan. Jika dia kembali lagi nanti dan berkata, Oh, itu benar-benar tidak memenuhi persyaratan bisnis saya, maka kita dapat meminta bayaran lebih banyak untuk melakukan apa yang kita suruh dia lakukan pertama kali. Seberapa banyak Anda dapat bernegosiasi dengan pelanggan tergantung pada seberapa besar mereka memercayai keahlian Anda, bagaimana kontrak mereka dengan Anda cocok dengan organisasi, dan, jujur ​​saja, seberapa keras kepala mereka.

Ini akan menjadi kasus yang sangat langka di mana, dengan asumsi itu terserah saya, saya akan kehilangan kontrak karena saya pikir persyaratannya salah dipahami.

Ingatlah bahwa orang yang dinegosiasikan dengan perusahaan Anda mungkin atau mungkin bukan orang yang menemukan aturan 25% ini. Ini bisa menjadi aturan yang dikenakan pada mereka dari atasan.

Saya melihat lima kemungkinan tanggapan:

Satu. Yakinkan bos Anda atau siapa pun yang sedang bernegosiasi dengan klien untuk berdebat tentang hal ini. Mustahil ini tidak menghasilkan apa-apa, tetapi Anda bisa mencobanya.

Dua. Menolak melakukannya. Ini mungkin akan membuat Anda dipecat, atau jika perusahaan setuju dengan Anda, menyebabkan Anda kehilangan kontrak. Ini sepertinya tidak produktif.

Tiga. Tulis komentar tidak berguna untuk mengisi ruang, jenis komentar yang hanya mengulangi apa yang ada dalam kode dan bahwa setiap programmer yang mampu memodifikasi kode dapat melihat dalam 2 detik. Saya telah melihat banyak komentar seperti ini. Bertahun-tahun yang lalu saya bekerja untuk sebuah perusahaan di mana kami diminta untuk menempatkan blok komentar di depan setiap fungsi yang mencantumkan parameter, seperti:

/*
GetFoo function
Parameters:
  name: String, contains name
  num: int, the number
  add_date: date, the date added
Returns:
  foo code: int
*/
int GetFoo(String name, int num, Date add_date)

Keberatan bahwa komentar tersebut adalah beban pemeliharaan karena Anda harus tetap memperbaruinya tidak valid. Tidak perlu memperbarui mereka karena tidak ada programmer serius yang akan melihatnya. Jika ada pertanyaan tentang itu, pastikan untuk menjelaskan kepada semua anggota tim bahwa komentar yang tidak berguna dan berlebihan harus diabaikan. Jika Anda ingin tahu apa parameter suatu fungsi atau apa yang dilakukan oleh baris kode, baca kodenya, jangan lihat komentar yang tidak berguna.

Empat Jika Anda akan menambahkan komentar tidak berguna yang berlebihan, mungkin ada baiknya Anda menulis program untuk menghasilkannya. Sesuatu investasi di muka, tetapi bisa menghemat banyak mengetik di jalan.

Kembali ketika saya pertama kali memulai dalam bisnis ini, sebuah perusahaan tempat saya bekerja menggunakan program yang diiklankan sebagai "Menulis dokumentasi Anda untuk Anda! Dokumentasi lengkap untuk setiap program!" Sistem mengharuskan kami memberikan semua variabel pada dasarnya nama yang tidak berarti dan kemudian memiliki tabel yang memberikan nama yang bermakna untuk setiap variabel, jadi pada dasarnya yang dilakukan "dokumentasi otomatis" adalah mengganti nama yang tidak berarti yang memaksa kami untuk menggunakan dengan nama yang bermakna. Jadi misalnya - ini bekerja dengan COBOL - Anda akan memiliki garis dalam program Anda yang mengatakan

MOVE IA010 TO WS124

dan mereka akan menghasilkan garis "dokumentasi" yang mengatakan

COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE

Bagaimanapun, orang pasti bisa menulis sebuah program untuk menghasilkan dokumentasi yang sama tidak berharga dengan cukup mudah. Baca garis seperti

a=b+c

dan menghasilkan komentar

// add b to c and save result in a

Dll

Lima. Buat yang terbaik dari aturan konyol. Cobalah untuk menulis komentar yang bermanfaat dan bermakna. Hei, ini bisa menjadi latihan yang bagus.

Oh, omong-omong, bolehkah saya menambahkan bahwa Anda selalu bisa memainkan metrik.

Saya ingat ketika seorang majikan mengatakan bahwa mereka akan mulai mengukur produktivitas pemrogram dengan berapa banyak baris kode yang kami hasilkan per minggu. Ketika kami diberitahu hal ini di sebuah rapat, saya berkata, Hebat! Saya dapat dengan mudah meningkatkan skor saya. Tidak ada lagi tulisan

x=x+4;

Sebagai gantinya saya akan menulis:

x=x+1;
x=x+1;
x=x+1;
x=x+1;

Loop? Lupakan, saya akan menyalin dan menempelkan kode sepuluh kali. Dll

Jadi di sini, jika mereka akan menghitung baris komentar, buat setiap baris pendek dan lanjutkan ide pada baris berikutnya. Jika ada perubahan pada komentar, jangan perbarui komentar yang ada. Masukkan tanggal di atasnya, lalu salin seluruh teks dan tulis "Diperbarui" dan tanggal baru. Jika klien mempertanyakannya, beri tahu mereka bahwa Anda perlu menjaga riwayatnya. Dll.


2

Metrik sewenang-wenang tampaknya menjadi fakta kehidupan dalam terlalu banyak proyek ...

Ini sering terlihat dalam persyaratan bodoh seperti kompleksitas Siklomatik maksimum yang mengarah ke kode yang lebih kompleks, karena fungsi tidak perlu dipisah untuk memastikan kepatuhan, atau file yang dipisah karena melebihi beberapa panjang SLoC sewenang-wenang

Komentar harus ditambahkan ke kode, dan jelaskan apa yang sedang terjadi (dan tidak hanya mengulangi kode!).

Yang mengatakan, jika ini yang diinginkan pelanggan Anda, dan perusahaan Anda telah setuju untuk menyediakan, kecuali Manajer QA Anda mengembangkan dosis yang masuk akal, Anda mandek.


Iya. Aturan sewenang-wenang menyebabkan orang memodifikasi perilaku mereka untuk mengambil keuntungan dari aturan tersebut. Inilah masalah dengan birokrasi. Itu membuat saya bingung bagaimana orang dapat membuat aturan dan tidak menganggap bahwa orang yang terpengaruh oleh aturan dapat mempertimbangkannya saat memutuskan apa yang harus dilakukan. Kemudian mereka membuat lebih banyak aturan untuk menyumbat celah, dan lebih banyak aturan untuk memasang lubang yang dibuat oleh celah, dll.
Jay

2

Dalam jangka pendek tidak ada yang bisa Anda lakukan. Ikuti saja.

Anda juga harus mengabaikan semua ide bodoh yang saya lihat di utas ini tentang protes agresif pasif dan lelucon konyol dalam kode.

Setelah Anda mengembangkan hubungan saling percaya dengan klien, mereka akan lebih siap untuk mendengarkan alasan Anda - Anda mungkin menemukan bahwa ini adalah permintaan konyol dari satu orang yang dulu berpengaruh dan bahwa ia memiliki sedikit dukungan di dalam perusahaan.

Dalam situasi apa pun sebaiknya Anda menentangnya tanpa izin klien.


2

Saya kecewa dengan kurangnya imajinasi yang ditampilkan oleh sesama programmer saya di sini.

Menurut saya klien melakukan riset. Dia mungkin telah membaca di suatu tempat bahwa kode kualitas biasanya berisi sekitar 25% komentar. Jelas dia peduli / khawatir tentang pemeliharaan di ujung jalan. Sekarang, bagaimana dia membuat beton itu dalam dokumen persyaratan yang harus terikat pada kontrak? Itu tidak mudah. Bahkan mungkin tidak mungkin. Namun dia ingin memastikan dia akan mendapatkan nilai untuk uangnya sehingga dia menyebutkan beberapa indikator kualitas.

Itu sama sekali tidak terdengar bodoh atau konyol bagi saya. Orang-orang yang menulis persyaratan kemungkinan besar bukan pemrogram. Mereka mungkin memiliki pengalaman buruk dengan proyek sebelumnya. Petugas pemeliharaan mereka mengeluh: "Semua omong kosong ini tidak didokumentasikan!" Ini berdering di telinga ketika mereka menulis persyaratan baru untuk proyek selanjutnya.

Jika Anda serius mendokumentasikan kode Anda dan menyediakan konteks untuk geng pemeliharaan, persyaratan ini akan dipenuhi secara otomatis. Jadi, jangan menjadi banci tentang itu!

Pada akhirnya, baik itu 21% atau 29%, tidak ada yang peduli. Klien akan memeriksa barang-barang Anda oleh beberapa pengembang independen dan dia akan lebih memahami apa yang Anda lakukan.


1
Pertanyaannya secara pasti membuktikan bahwa mengekspresikan tingkat komentar sebagai tujuan akan menjadi bumerang. Akan lebih efektif bagi klien untuk memiliki sasaran tujuan bahwa kode harus dapat dipahami oleh pengembang lain (dalam tim? Dari luar? Dengan latar belakang pengetahuan dan keterampilan apa?) Dan memberikan 25% sebagai pedoman (fleksibel). Mengungkapkannya dengan cara ini akan lebih dipahami oleh kontraktor, dan mendorong alternatif yang lebih baik, seperti kode bersih.
Christophe

0

Saya telah bertemu banyak programmer yang tidak mengerti bagaimana orang ada yang saat ini tidak bekerja pada proyek ini.

Bagi mereka semua yang mereka tahu, ADALAH diketahui oleh semua orang.

Jika seseorang tidak tahu SEMUA yang mereka ketahui saat ini, maka orang-orang itu adalah "idiot" bagi mereka.

Dengan standar ini Anda dapat memaksa orang untuk terbiasa menulis komentar.

Mereka mungkin menulis komentar yang tidak berguna 99% dari waktu, tetapi kadang-kadang mereka mungkin benar-benar menuliskan salah satu hal yang "SEMUA ORANG TAHU", dan seseorang yang baru dalam tim mungkin sebenarnya tidak menghabiskan 16 jam untuk mencari bug (yang sudah dipecahkan beberapa orang, tetapi kemudian dibatalkan karena alasan lain) yang sudah jelas dengan komentar pada saat itu dalam kode.

Memiliki komentar di baris dengan bug yang tidak terlihat juga dapat membantu menghindari programmer di masa depan untuk benar-benar menghancurkan program secara tidak sengaja (terutama ketika bagian "sedang rusak" tidak jelas ketika melakukan tes cepat).


3
Masalah dengan membiarkan 10.000 kera menggedor mesin ketik bukanlah bahwa mereka tidak pernah menulis sesuatu yang berharga, tetapi bahwa permata langka yang langka itu sulit ditemukan di tumpukan sampah.
Deduplicator
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.