Apakah normal / dapat diterima untuk menulis catatan, pemikiran, algoritma, keputusan selama pengkodean dan pemeliharaan? [Tutup]

22

Beberapa orang memiliki masalah ini yang tidak dapat mereka pikirkan tanpa kata-kata. Dan menuliskan pikiran dan keputusan mereka adalah cara paling efektif untuk melanjutkan.

Jadi - apakah itu normal dan dapat diterima bahwa saya menuliskan pemikiran dan keputusan saya dalam beberapa file Notepad ++ selama pengkodean?

Kadang-kadang harus diterima, misalnya ketika membuat kembali dokumentasi teknis atau alasan tentang algoritma yang lebih kompleks, tetapi kadang-kadang mungkin aneh, misalnya ketika saya mempertimbangkan opsi desain dan mencoba membuat penilaian.

Dampak praktik ini terhadap produktivitas tidak jelas. Dari satu sisi - beralasan dengan kata-kata batin mungkin lebih cepat daripada dengan kata-kata tertulis. Dari sisi lain - masalah yang lebih kompleks membutuhkan penulisan. Selain itu, jika seseorang terjebak dengan lebih banyak pilihan desain, maka perasaan lebih baik ketika keputusan ditulis, sehingga membangkitkan semangat.

Untuk Tuan
sumber
5
Saya cenderung melakukan ini juga, dan umumnya menyesal ketika saya tidak melakukannya. Sangat membantu untuk memiliki sesuatu untuk dilihat kembali nanti untuk mengingat mengapa Anda melakukan sesuatu dengan cara tertentu, atau untuk dapat membuat keputusan nanti ketika Anda tidak menyikutinya dengan visi terowongan. Ketika saya lupa mencatat sesuatu, saya biasanya lupa mengapa, dan kemudian menghabiskan lebih banyak waktu untuk menelusuri kembali langkah-langkah saya.
PseudoPsyche
21
Saya merasa kita kehilangan bagian dari konteks? Apakah pengamatan ini dilakukan seputar keluhan seputar efisiensi? Seringkali, kritik datang dengan saran untuk akar penyebab yang mungkin relevan atau tidak.
Jim Rush
9
"Komentar dan dokumentasi" perlu dituliskan ke dalam kode sumber dan disimpan. Pikiran Anda tentang mempertimbangkan opsi desain mungkin ditulis, tetapi biasanya tidak disimpan, itu adalah hal yang jarang akan membantu Anda nanti (Anda dapat membuat catatan tentang hasil dari proses pemikiran itu, jika tidak jelas dari kode sumber itu sendiri, tetapi bukan itu yang kamu tanyakan). Jika Anda lebih suka bentuk elektronik, bentuk pensil dan kertas, atau jika Anda dapat melakukan ini semua di kepala Anda, terserah Anda, tidak ada orang lain selain Anda dapat memberi tahu Anda apa yang paling cocok untuk Anda.
Doc Brown
4
... PS: Saya biasanya lebih suka pensil dan kertas, atau papan tulis untuk hal-hal ini, dan saya pikir saya tidak akan menjadi programmer yang lebih baik jika saya mencoba melakukan semua ini di kepala saya, justru sebaliknya.
Doc Brown
7
Mengapa itu tidak bisa diterima? Dapat diterima siapa?
Paul D. Waite

Jawaban:

62

Bukan hanya itu normal, itu ide yang bagus.

Ada kutipan terkenal

"Beri aku enam jam untuk menebang pohon dan aku akan menghabiskan empat pertama mengasah kapak".

Meluangkan waktu untuk mengatur pemikiran Anda dan merencanakan pekerjaan Anda sebelum pengkodean menghabiskan waktu dengan baik. Menempatkan pemikiran itu di atas kertas akan memberi Anda waktu untuk merenungkan rencana Anda, mengkritiknya, dan mengaturnya dengan cara yang akan sangat sulit jika dilakukan hanya "di kepala Anda".

Dan Pichelman
sumber
8
Ini kutipan yang bagus, meskipun saya akan menghapus atribusi yang salah. quoteinvestigator.com/tag/abraham-lincoln
Paul Draper
1
Tentunya pernyataan yang benar dan kutipan yang baik, tetapi untuk pemahaman saya pertanyaan itu memiliki fokus yang berbeda. Sejauh yang saya mengerti, OP tidak memiliki keraguan tentang pentingnya perencanaan sebelumnya. Dia bertanya apakah lebih efisien untuk menuliskan pemikiran / perencanaan ini, atau hanya menyimpan semua itu hanya di kepalanya saja.
Doc Brown
2
Menurut Anda satu jam mengasah lebih dari cukup. Tugas ini seharusnya diperkirakan maksimal 3 jam, tetapi slack telah dihabiskan untuk persiapan berlebih yang sia-sia. Apa yang menjadi moral lagi? ;-)
Steve Jessop
26

Ya, ini bisa diterima dan normal.

Mendokumentasikan proses pembuatan keputusan Anda seringkali berharga ketika meninjau kembali kode, untuk membantu menentukan mengapa kode ditulis dengan cara tertentu.

Catatan ini dapat dimasukkan secara langsung dalam kode sebagai komentar, jika cukup singkat. Komentar yang diperluas sering disimpan sebagai bagian dari dokumen desain teknis eksternal.

mcknz
sumber
4
Saya akan sangat menyarankan untuk tidak memasukkan catatan tentang mempertimbangkan opsi desain dan mencoba membuat penilaian sebagai komentar dalam kode sumber, ini tidak pernah "cukup pendek". Hanya hasil akhir dari proses pemikiran itu, tetapi itu sangat berbeda dari apa yang diminta OP.
Doc Brown
3
Saya sering menemukan diri saya dalam diskusi sepanjang baris "mengapa kita membuat keputusan ini." Sangat membantu untuk kembali ke catatan proyek harian saya untuk memberikan konteks, termasuk alternatif yang kami diskusikan. Saya pikir saya di perusahaan yang baik: menurut The Everything Store Jeff Bezos melakukan hal yang sama.
kdgregory
8
@DocBrown - kadang-kadang itu adalah ide yang baik untuk memasukkan alasan mengapa Anda tidak menggunakan metode / algoritma lain yang mungkin sehingga pengembang masa depan tidak akan mencoba untuk mengganti apa yang telah Anda lakukan
HorusKol
1
@HorusKol: tentu saja, dalam beberapa kasus yang jarang, itu adalah hal biasa yang sepele. Tapi itu sangat berbeda dari "mendokumentasikan proses pengambilan keputusan" .
Doc Brown
1
@DocBrown benar, saya tidak berpikir ada yang mau halaman catatan dalam kode sumber mereka. :)
mcknz
20

Itu ide yang bagus. Sampai itu menjadi cara untuk menunda-nunda.

Kuncinya adalah keseimbangan. Saya menemukan saya paling produktif jika saya tidak memasukkan diri saya tetapi menangkap ide ketika mereka datang.

Jika saya menggiling pada level rendah dan ide level tinggi datang, saya hanya menuliskannya dan kembali lagi nanti.

Merencanakan pekerjaan adalah ide yang baik tetapi kecuali Anda harus berkomunikasi atau hadir di depan audiens alat terbaik adalah pena dan serbet. Tangkap ide itu. Jangan buang waktu untuk membuatnya cantik.

candied_orange
sumber
Penurunan harga adalah cara hebat lainnya untuk mencatat ini. Letakkan tangan Anda di atas keyboard, jadi ada sedikit gangguan pada proses berpikir.
RubberDuck
1
Apakah menyalakan editor atau mengambil pena dan serbet adalah alternatif yang lebih baik sepenuhnya tergantung pada keterampilan mengetik dan menulis tangan pribadi Anda. Bagi saya, solusi yang lebih baik adalah editor.
cmaster
9

Dalam situasi profesional apa pun, itu tidak hanya "normal dan dapat diterima", itu wajib. Siklus pengembangan yang khas terdiri dari dua fase dokumentasi sebelum pengkodean dimulai.

  1. Dokumen Persyaratan Fungsional: biasanya ditulis oleh analis bisnis, menentukan fungsi yang akan diterapkan.

  2. Dokumen Desain Detail: yang cukup banyak dengan apa yang Anda bicarakan, hanya lebih formal, menentukan dekomposisi fungsional (anjak piutang) dari sistem, algoritma, dll. Beberapa (lama) saya yang lama sedang online, misalnya ini .

Untuk dokumentasi yang kurang formal, saya 110% setuju dengan komentar sebelumnya tentang komentar sebaris. Itu satu - satunya cara untuk pergi; dengan satu atau lain cara, segalanya akhirnya hilang. Tetapi komentar inline yang rapi dan bijaksana adalah keterampilan pengkodean terpisah, yang dikembangkan melalui upaya dan praktik seperti keterampilan lainnya. Anda dapat melihat beberapa barang lama saya di, misalnya ini . Gaya itu mungkin atau mungkin tidak menarik bagi Anda. Saya sarankan terlebih dahulu menemukan beberapa kode yang dikomentari dengan gaya yang Anda suka, dan meniru itu dalam kode Anda sendiri. Setelah beberapa saat, sesuaikanlah sesuai keinginan Anda.

John Forkosh
sumber
4

Tempat yang tepat untuk menaruh informasi semacam ini secara langsung di pesan commit dari sistem kontrol versi Anda (SVN, git, dll). Dengan cara ini Anda bisa melihat perubahan dan alasannya di tempat yang sama.

Derek
sumber
1
Itu juga membuat mereka dapat dicari. Anda dapat mencari pesan komit di commandline git dan sourcetree misalnya .. Jika Anda hanya menggunakan notepad, kemungkinan besar file tidak akan pernah dibuka lagi dan sulit untuk mencari tanpa mengetahui beberapa bash yang luas dan menulis skrip yang mencari semua tempat yang relevan.
HopefullyHelpful
Saya mencoba melakukan ini di kedua pernyataan komit saya serta permintaan bug atau fitur dengan tautan ke komit. Saya juga melakukan komentar inline tanggal dalam kode dengan alasan mengapa saya mengubah kode. Ini membantu secara dramatis dalam basis kode lama kami yang berderit di mana komentar sebagian besar tidak diketahui.
delliottg
Tidak, ini sesuatu yang lain. Pesan komit harus menggambarkan apa yang dilakukan, bukan mengapa. Alasannya ada dalam dokumentasi kode Anda, komentar, dokumentasi yang menyertainya, dan resolusi pelacak masalah. Anda tidak dapat memasukkan lima halaman catatan dan karya desain ke dalam pesan komit, dan Anda juga tidak perlu melakukannya.
Lightness Races dengan Monica
Sangat bagus untuk meletakkannya di sistem kontrol versi. Tempat yang lebih baik adalah file teks biasa di dalamnya. Itu lebih mudah digunakan daripada melakukan pesan.
Thorbjørn Ravn Andersen
2

Selain jawaban baik lainnya, saya akan menambahkan bahwa saya sering menuliskan pikiran saya tentang apa yang saya coba lakukan.

Menjadi sangat eksplisit tentang mengartikulasikan apa yang saya coba lakukan membantu saya menyadari anggapan, asumsi dan / atau persyaratan yang tidak selalu berlaku.

Itu kemudian mengisyaratkan alternatif, yang kemudian saya dapat memikirkan lebih baik masing-masing pada gilirannya; tulisan itu membantu menyelamatkan tempat saya jika saya memikirkan sesuatu yang lain.

Saya membuat catatan cepat untuk mengeksplorasi napas dan kedalaman, sehingga ia bekerja secara rekursif, membantu saya menguraikan, menavigasi, dan mengevaluasi pohon solusi, mencadangkan, mengeksplorasi, menemukan, menyadari, dan memutuskan.

Erik Eidt
sumber
1

Menulis apa pun yang dapat menghemat waktu Anda / anggota tim (baru) adalah waktu yang dihabiskan dengan baik. Pastikan itu adalah sesuatu yang mungkin dibutuhkan seseorang di kemudian hari dan jangan terlalu banyak berpikir kecuali itu adalah proyek jangka panjang yang nyata.

Ini juga tidak perlu waktu sama sekali. Jika Anda menghabiskan waktu untuk berpikir, Anda dapat menuliskan pemikiran Anda 1 banding 1 (selama itu akan / dapat bermanfaat bagi seseorang).

Masalah sebenarnya bisa terlalu memikirkan apa yang Anda tulis. Hanya karena Anda menulis bukan berarti Anda harus mematuhi beberapa format yang sudah ada atau perlu semua cara membuat dokumentasi lengkap.

Jika pilihan Anda adalah antara tidak menuliskan apa pun dan hanya menulis catatan tidak formal pada notepad, maka cukup tulis catatan tidak formal.

Semoga Membantu
sumber
1

Anda berkata: "Beberapa orang memiliki masalah ini sehingga mereka tidak dapat berpikir tanpa kata-kata. Dan menuliskan pikiran dan keputusan mereka adalah cara paling efektif untuk melanjutkan."

Jika menuliskan pikiran dan keputusan Anda adalah cara yang paling efektif untuk melanjutkan, mengapa tidak normal dan dapat diterima untuk melanjutkan dengan cara yang paling efektif? Anda melakukan yang terbaik untuk Anda. Mungkin bukan yang terbaik untuk orang lain. Dalam hal ini Anda tidak membiarkan orang lain memberi tahu Anda apa yang terbaik untuk Anda, dan Anda tidak memberi tahu mereka apa yang terbaik untuk mereka. Setiap orang melakukan yang terbaik untuk mereka.

gnasher729
sumber
1

Manusia hanya bisa memegang sekitar tujuh "benda" di kepala mereka sekaligus. Itulah alasan nomor telepon tujuh digit. Agar pemrogram dapat bekerja secara efisien, mereka harus menemukan semacam sistem untuk melepaskan barang dari memori mereka dan dengan cepat mengambilnya nanti sesuai kebutuhan. Catatan Anda adalah cara yang jelas dan langsung, tetapi semua orang yang mengerjakan sesuatu yang cukup rumit harus melakukannya entah bagaimana . Saat Anda memasangkan program dengan seseorang, buat titik untuk mencari metode mereka.

Salah satu cara yang umum adalah pengembangan yang digerakkan oleh tes. Dalam metodologi ini, Anda menulis satu tes gagal, Anda menulis kode yang cukup untuk lulus tes gagal, kemudian Anda refactor kode Anda agar terlihat lebih bagus sambil menjaga semua tes yang ada Anda lulus. Metodologi ini menyimpan semua "catatan" Anda dikodekan di dalam tes. Orang dapat bekerja sangat cepat dengan cara ini tanpa terlihat mencatat, karena mereka hanya fokus pada tes selanjutnya.

Cara umum lainnya adalah dengan hanya menulis catatan Anda dalam kode Anda sebagai komentar pseudocode atau bertopik, kemudian secara bertahap menggantikannya dengan hal yang nyata. Beginilah biasanya saya menulis algoritma. Draf pertama saya hanyalah fungsi utama dengan pseudocode, kemudian secara bertahap mengisi ke tingkat abstraksi yang lebih dalam dan lebih dalam.

Jangan merasa bersalah menggunakan metode apa pun yang cocok untuk Anda, tetapi cobalah perhatikan metode apa yang digunakan oleh rekan "efisien" Anda. Mereka memiliki keterbatasan manusia yang sama seperti Anda.

Karl Bielefeldt
sumber
1
TDD adalah latihan mencatat? Saya kira tidak.
Robert Harvey