Praktik Terbaik untuk Menyerahkan Kode Warisan

66

Dalam beberapa bulan seorang kolega akan pindah ke proyek baru dan saya akan mewarisi salah satu proyeknya. Untuk mempersiapkan, saya sudah memesan Michael Feathers ' Bekerja Efektif dengan Kode Legacy .

Tapi buku-buku ini serta sebagian besar pertanyaan tentang kode warisan yang saya temukan sejauh ini berkaitan dengan kasus mewarisi kode apa adanya. Tetapi dalam kasus ini saya benar-benar memiliki akses ke pengembang asli dan kami punya waktu untuk penyerahan tertib.

Beberapa latar belakang pada potongan kode yang akan saya warisi:

  • Ini berfungsi: Tidak ada bug yang dikenal, tetapi karena persyaratan kinerja terus meningkat, beberapa optimasi akan diperlukan dalam waktu yang tidak lama lagi.
  • Tidak berdokumen: Ada hampir nol dokumentasi pada tingkat metode dan kelas. Apa yang seharusnya dilakukan oleh kode pada tingkat yang lebih tinggi, dipahami dengan baik, karena saya telah menulis menentang API-nya (sebagai kotak hitam) selama bertahun-tahun.
  • Hanya tes integrasi tingkat yang lebih tinggi: Hanya ada tes integrasi yang menguji interaksi yang tepat dengan komponen lain melalui API (sekali lagi, kotak hitam).
  • Tingkat sangat rendah, dioptimalkan untuk kecepatan: Karena kode ini merupakan pusat dari seluruh sistem aplikasi, banyak dari kode tersebut telah dioptimalkan beberapa kali selama bertahun-tahun dan tingkatnya sangat rendah (satu bagian memiliki manajer memori sendiri untuk struktur tertentu / catatan).
  • Bersamaan dan bebas-kunci: Sementara saya sangat akrab dengan pemrograman bersamaan dan bebas-kunci dan sebenarnya telah berkontribusi beberapa bagian untuk kode ini, ini menambah lapisan kompleksitas lainnya.
  • Basis kode besar: Proyek khusus ini lebih dari sepuluh ribu baris kode, jadi tidak mungkin saya bisa menjelaskan semuanya kepada saya.
  • Ditulis dalam Delphi: Saya hanya akan menempatkan ini di luar sana, meskipun saya tidak percaya bahasanya cocok dengan pertanyaan, karena saya percaya jenis masalah ini adalah agnostik bahasa.

Saya bertanya-tanya bagaimana waktu sampai kepergiannya sebaiknya dihabiskan. Berikut adalah beberapa ide:

  • Dapatkan semuanya untuk dibangun di mesin saya: Meskipun semuanya harus diperiksa ke dalam kontrol kode sumber, yang tidak pernah lupa untuk memeriksa file sesekali, jadi ini mungkin harus menjadi urutan pertama bisnis.
  • Lebih banyak tes: Sementara saya ingin lebih banyak tes unit tingkat kelas sehingga ketika saya akan membuat perubahan, bug apa pun yang saya perkenalkan dapat ditangkap sejak awal, kode seperti sekarang tidak dapat diuji (kelas besar, metode panjang, terlalu banyak saling ketergantungan).
  • Apa yang harus didokumentasikan: Saya pikir sebagai permulaan akan lebih baik untuk memfokuskan dokumentasi pada area-area dalam kode yang jika tidak akan sulit untuk dipahami misalnya karena sifat tingkat rendah / sangat dioptimalkan. Saya takut ada beberapa hal di sana yang mungkin terlihat jelek dan membutuhkan refactoring / penulisan ulang, tetapi sebenarnya optimasi yang telah ada di sana untuk alasan yang baik yang mungkin saya lewatkan (lih. Joel Spolsky, Hal yang Seharusnya Anda Lakukan) Never Do, Bagian I )
  • Cara mendokumentasikan: Saya pikir beberapa diagram kelas dari arsitektur dan diagram urutan fungsi kritis disertai dengan beberapa prosa akan menjadi yang terbaik.
  • Siapa yang harus didokumentasikan: Saya bertanya-tanya apa yang lebih baik, meminta dia menulis dokumentasi atau meminta dia menjelaskannya kepada saya, sehingga saya dapat menulis dokumentasinya. Saya takut, bahwa hal-hal yang jelas baginya tetapi bukan saya kalau tidak tidak akan dibahas dengan baik.
  • Refactoring menggunakan pair-programming: Ini mungkin tidak mungkin dilakukan karena keterbatasan waktu, tapi mungkin saya bisa memperbaiki beberapa kode-nya agar lebih mudah dikelola sementara dia masih ada untuk memberikan masukan mengapa hal-hal seperti itu adanya.

Silakan komentari dan tambahkan ini. Karena tidak ada cukup waktu untuk melakukan semua ini, saya sangat tertarik pada bagaimana Anda memprioritaskan.

Pembaruan: Ketika proyek serah selesai, saya telah memperluas daftar ini dengan pengalaman saya sendiri dalam jawaban di bawah ini .

PersonalNexus
sumber
2
Fokus pada mendokumentasikan mengapa fungsi yang dioptimalkan!
Saya harap kode di bawah kendali sumber. Jika demikian, Anda akan mendapat manfaat dari komentar yang dimasukkan untuk setiap perubahan (jika ada).
Bernard
Panggilan yang baik untuk menggunakan Michael Feathers 'Bekerja Efektif dengan Legacy Code. Pasti harus mulai mendapatkan test case yang ditulis di sekitar modul yang Anda pikir paling mungkin perlu dimodifikasi. Jika Anda mulai sekarang, akan lebih mudah untuk mendapatkan harapan yang benar.
Bill Leeper
Ada fase sebelum refactoring, yang saya ragukan internetnya kurang baik dalam menjawab: Apa yang dilakukan programmer top untuk memahami kode rumit dan tidak terbaca orang lain?
sergiol

Jawaban:

25

Ketika Anda memiliki akses ke pengembang kode Anda bertanya: -

  • Modul mana yang paling sulit dikodekan / diimplementasikan. Apa masalahnya dan bagaimana mengatasinya.

  • Modul mana yang paling banyak menghasilkan bug.

  • Modul mana yang menghasilkan bug paling sulit untuk diselesaikan.

  • Bit kode mana yang paling ia banggakan.

  • Bit kode mana yang ingin dia refactor, tetapi belum punya waktu.

Pertanyaan-pertanyaan ini akan memberi Anda wawasan tentang apa yang akan menyebabkan Anda paling banyak masalah, dan, mungkin yang lebih penting pegangan pada proses pemikiran dan perspektif pengembang asli.

James Anderson
sumber
Saya suka ide memilih bagian yang Anda sebutkan. Secara intuitif, saya akan mengikuti top-down tetapi dengan cara itu bagian-bagian paling jahat yang terkubur jauh di dalam kode mungkin tidak muncul sampai sangat terlambat, mungkin terlalu terlambat dalam proses. Cara Anda lebih masuk akal, saya pikir. Apakah Anda memiliki saran untuk bagian "cara mendokumentasikan"? UML? Teks?
PersonalNexus
@PersonalNexus. Anda dapat membawa pendekatan ini ke dokumentasi juga. Tanyakan dokumen mana yang paling berguna, dan, dokumen mana yang tidak dapat diandalkan atau ketinggalan zaman (percayalah padaku 95% dokumentasi termasuk dalam kategori terakhir!).
James Anderson
17

Karena proyek serah terima sekarang, saya pikir saya akan meluangkan waktu dan menulis jawaban saya sendiri yang berisi hal-hal yang paling cocok untuk saya.

  • Dapatkan semuanya di bawah kontrol versi: Setelah memastikan semua yang saya butuhkan untuk membangun berada di bawah kontrol versi, saya juga mencari di hard drive pengembang lama, untuk mencari skrip atau utilitas tambahan yang akan membantu untuk menyebarkan dan / atau menguji aplikasi tetapi tidak sudah check-in.
  • Top-down: Saya akan memulai dengan tampilan tingkat tinggi di kelas-kelas utama dan tur berpemandu dengan pengembang lama di area utama. Kemudian saya akan menggali lebih dalam pada sisanya sendiri, menandai hal-hal yang tidak masuk akal bagi saya dengan //TODOspidol.
  • Tulis semua dokumentasi sendiri: Sementara saya meminta pengembang lama memeriksa tulisan saya untuk memastikan saya melakukannya dengan benar, saya bersikeras untuk menulis semuanya sendiri. Dengan cara ini saya yakin tulisan itu masuk akal bagi saya dan bukan hanya pengembang lama.
  • Komentar di mana-mana: Saya menambahkan ringkasan dokumentasi XML ke setiap kelas dan setiap metode. Dengan cara ini saya memastikan setidaknya saya telah melihat setiap bagian kode dan memiliki cukup pemahaman untuk merangkum apa yang dilakukannya dalam sebuah kalimat. Ini juga membuat memahami metode menggunakan metode ringkasan / kelas lebih mudah saat IntelliSense mengambil informasi ini. Saya juga bisa dengan mudah mengidentifikasi area kode yang masih harus saya lihat.
  • Dokumen dekat dengan sumber: Untuk membuat koneksi antara kode sumber dan dokumentasi lebih mudah, saya meletakkan sebagian besar dokumentasi saya tepat di kode sumber. Untuk dokumentasi tingkat tinggi yang menggambarkan interaksi antara berbagai sub-sistem, saya menggunakan wiki, karena meletakkan informasi ini hanya di satu tempat dalam kode tidak berfungsi. Semua dokumentasi harus elektronik dan teks lengkap dapat dicari.
  • Diagram: Untuk gambaran umum dasar saya menggunakan diagram kelas dari berbagai rincian untuk berbagai sub-sistem. Untuk bagian bersamaan, objek dan diagram interaksi sangat membantu; lihat juga pertanyaan saya yang lain tentang topik tersebut .
  • Refactoring sebagai pasangan: Sementara saya melakukan beberapa refactoring dengan pengembang lama untuk merasakan kode dan membuat hal-hal lebih dapat dipertahankan, ini adalah proses yang memakan waktu dan juga berisiko, karena kurangnya alat refactoring yang baik dan banyak yang tidak menyenangkan ketergantungan antara berbagai bagian. Bekerja dengan Efektif dengan Legacy Code dari Michael Feathers adalah bantuan yang sangat baik untuk ini, walaupun refactoring tanpa dukungan alat yang tepat masih menyakitkan. Sementara refactoring saya akan membiarkan dia memiliki kontrol mouse dan keyboard, karena itu lebih menyenangkan baginya dengan cara ini (lihat juga poin terakhir saya) dan saya bebas untuk menuliskan apa yang saya pelajari.
  • Check-in terpisah untuk komentar dan perubahan: Setelah saya secara tidak sengaja memperkenalkan bug dengan menulis komentar di atas override, saya telah berhati-hati untuk membuat komentar dan perubahan pada check-in terpisah. Saya menggunakan sedikit utilitas untuk menghapus semua komentar dari kode sumber sebelum memeriksa sesuatu, jadi perbedaan dari komentar-saja akan menunjukkan 0 perbedaan. Semua perubahan (mis., Penghapusan bidang yang tidak digunakan) dengan seksama ditinjau oleh pengembang lama untuk memastikan saya tidak menghapus hal-hal yang masih diperlukan.
  • Panduan singkat baris demi baris untuk bagian-bagian penting: Untuk bagian yang paling optimal / kompleks, saya akan membahas kode baris demi baris dengan pengembang lama dan kadang-kadang bahkan dengan kolega ketiga. Dengan cara ini saya mendapatkan pemahaman menyeluruh tentang kode dan karena semakin banyak orang memeriksa kode, kami sebenarnya mengidentifikasi beberapa bug serta beberapa hal yang dapat dioptimalkan lebih lanjut.
  • Cepat dan terus termotivasi pengembang lama: Saya perhatikan bahwa pengembang lama kurang dan kurang tertarik karena hari terakhirnya semakin dekat (tidak mengherankan). Karena itu saya akan memastikan bagian-bagian yang paling penting diserahkan terlebih dahulu, meninggalkan sisanya bagi saya untuk mencari tahu sendiri, jika perlu. Saya juga mencoba untuk meninggalkan hal-hal yang lebih menyenangkan (mis. Kontrol keyboard saat pair-programming) kepadanya dan melakukan hal-hal yang membosankan seperti dokumentasi menulis sendiri.
  • Identifikasi permintaan fitur: Saya merasa terbantu untuk meminta daftar fitur yang telah diminta oleh pengembang lama tetapi belum ditambahkan. Ada beberapa hal yang bagi saya terlihat sederhana untuk ditambahkan, tetapi di mana ada alasan bagus mereka tidak ditambahkan karena mereka akan merusak hal-hal lain ketika diterapkan seperti yang saya pikirkan pada awalnya.
PersonalNexus
sumber
14

Setelah berada dalam situasi yang sama, saya percaya hal-hal berikut ini juga layak dipertimbangkan:

  • Pastikan Anda dapat melakukan, dan menguji, penyebaran: Lakukan penyebaran produk Anda sendiri, dari awal - dan verifikasi bahwa ini identik dengan yang dilakukan oleh orang yang pergi. Ini akan memastikan bahwa setiap skrip dan instruksi jelas bagi Anda, dan akan menangkap kesalahan yang tidak disengaja seperti bahan yang belum diperiksa ke sistem kontrol versi Anda. (Saya tidak mengatakan bahwa ini akan terjadi, hanya saja jika telah terjadi, maka akan jauh lebih mudah untuk berurusan dengan sekarang, sebelum orang tersebut meninggalkan)

    (Ini mungkin tidak relevan untuk Anda, misalnya jika Anda sudah melakukan Integrasi Berkelanjutan atau Penerapan Berkelanjutan, tetapi perlu disebutkan, untuk berjaga-jaga ...)

  • Menulis lebih banyak tes: Ini adalah cara yang sangat baik untuk menguji pemahaman Anda tentang suatu sistem. Ini akan memungkinkan (atau memaksa) Anda untuk melihat lebih dekat pada area kode, dan baik akan mengkonfirmasi bahwa kode tersebut bebas bug seperti yang Anda duga, atau akan mengungkapkan area di mana Anda pikir Anda memahami maksudnya, tetapi itu sebenarnya Anda perlu meminta kolega Anda untuk klarifikasi sebelum dia pergi

  • Dokumentasi pasangan-menulis: Ini adalah cara yang efektif untuk menulis ikhtisar. Saya menyarankan agar Anda meminta kolega Anda untuk menggambarkan fitur atau bidang, dan kemudian Anda menuliskannya, dalam dokumentasi, dengan kata-kata Anda sendiri. Kami menemukan ini jauh lebih mudah ketika dilakukan oleh dua orang bersama.

Saya akan menempatkan penulisan tes sebagai prioritas yang lebih tinggi daripada menulis dokumentasi, secara pribadi, karena tes mungkin akan memberi Anda lebih banyak - atau lebih kuat - pemahaman.

Mengenai Refactoring menggunakan pair-programming , satu-satunya hal yang saya katakan adalah bahwa ada bahaya bahwa ini bisa menjadi jurang bawah, terutama mengingat Anda mengatakan Anda hanya mendapatkan tes tingkat tinggi. Anda mungkin menemukan itu berakhir menggunakan jauh lebih banyak waktu yang tersedia daripada yang Anda inginkan.

Clare Macrae
sumber
+1 lebih banyak tes. tidak pernah ada cukup tes.
Sardathrion
10

+1 untuk jawaban yang sudah Anda miliki di pertanyaan Anda!

Tur
10k baris kode terpandu banyak, tapi saya pikir masih tidak mungkin untuk meminta orang lain memberi Anda 'tur berpemandu'. Anda duduk bersama di depan kode dan dia membawa Anda dalam perjalanan dari atas ke bawah, mengerjakan 'lapisan'. Anda harus melakukannya dalam ledakan singkat - semuanya akan membunuh Anda berdua sekaligus.

Zoom-in, zoom-out
Keuntungan dari melakukan ini adalah bahwa sementara dia menjelaskannya kepada Anda, dia hampir pasti akan memiliki beberapa momen "oh, ya, ini juga" yang mungkin tidak dia lakukan jika dia hanya mencoba mendokumentasikannya sendirian. Dan pertanyaan Anda akan membantu memusatkan perhatian pada hal-hal yang jelas-baginya-tetapi-tidak-untuk-siapa pun. Interaksi zoom-in / zoom-out semacam ini hanya mungkin dilakukan satu-satu, mencoba menulis atau membaca sesuatu seperti itu sangat sulit.

Dokumentasi
Saya pikir Anda berdua harus secara independen mendokumentasikan hal-hal - ia harus mulai dari bawah (jika Anda tidak punya waktu untuk sampai ke sana bersama-sama), dan Anda harus mulai dari atas, berdasarkan apa yang Anda mengerti turnya yang dipandu dan seolah-olah itu untuk orang lain [dalam pekerjaan sebelumnya saya mewarisi banyak kode 'warisan', dan hanya punya waktu untuk mendokumentasikannya sebelum pergi sendiri :)].

Dimana apa
Tujuan dari sebagian besar ini adalah agar Anda dapat merasakan di mana hal-hal terjadi. Sehingga dengan memberikan bug atau modifikasi tertentu, Anda dapat dengan cepat menemukan tempat dalam kode yang perlu Anda konsentrasi. Anda dapat menguji diri dengan mengambil daftar bug lama dan melihat apakah Anda dapat memprediksi secara akurat di mana masalahnya.

Pompa dia kering.
Tidak masalah jika dia akhirnya membencimu (tersenyum), tugasmu adalah mendapatkan sebanyak mungkin informasi dari otak lelaki itu sebanyak yang kamu bisa pada waktu yang tersedia. Pastikan Anda memiliki manajemen di pihak Anda, dan bahwa mereka memprioritaskan transfer pengetahuan daripada "hanya memperbaiki beberapa bug terakhir sebelum dia pergi" (kecuali jika Anda memperbaiki mereka bersama-sama ...).

Benjol
sumber
+1 untuk mencoba memperbaiki beberapa bug lama sendiri untuk menguji pemahaman saya tentang kode
PersonalNexus
1
"Tidak masalah jika dia akhirnya membencimu" - hati-hati, "ini dunia kecil";)
retracile
Juga, buka dokumen kata dan dokumentasikan heck hidup dari segalanya, termasuk satu ton screenshot. Ini menyelamatkan saya berkali-kali ketika Anda dalam kondisi informasi yang berlebihan!
Ben Power
7

Saya menyarankan yang berikut (selain apa yang sudah diidentifikasi) - Pertama, minta manajer Anda untuk memberi Anda waktu untuk bekerja dengan orang ini sebanyak mungkin dan mencoba untuk duduk dengannya setiap kali ia ditugaskan melakukan perubahan. Anda tidak harus tahu semua yang dia lakukan tetapi cobalah untuk menangkap sebanyak yang Anda bisa. Paling penting berteman dengan dia.

Perlakukan penyerahan sebagai proyek dan letakkan rencana di tempatnya dan libatkan manajemen.

0 - Pastikan Anda tahu cara menggunakan sistem.

1 - Buat inventaris yang jelas dari komponen solusi, sumber masing-masing dan di mana letaknya (dalam repositori berbeda)

2 - Dapatkan dan jika mungkin, kelola, kata sandi untuk berbagai server mulai sekarang. Pastikan Anda memiliki semua informasi akun admin

3 - Dapatkan lisensi dari setiap komponen eksternal kecuali di luar ruang lingkup Anda (misalnya dll, database, dll. Khusus)

4 - Dapatkan laporan tertulis tentang status sistem saat ini dari pengembang dan pelanggan Anda (jika mereka lokal untuk perusahaan Anda)

5 - Dapatkan dokumentasi untuk aturan bisnis, rumus perhitungan, dll. Anda dapat melakukan ini dengannya. Minta email, informasi rapat, dokumen kebutuhan pengguna, dokumen desain, dan sejenisnya untuk diberikan kepada Anda.

6 - Dapatkan daftar acara terjadwal (pekerjaan bulanan, pekerjaan mingguan) yang harus ditanggapi oleh perangkat lunak

7 - Pelajari prosedur pencadangan / pengembalian

8 - Memahami kerangka yang digunakan dalam membangun aplikasi

9 - Kenali modifikasi yang diminta / diharapkan / direncanakan dan status dari setiap permintaan pengguna yang tertunda. Mulailah mencoba mengidentifikasi cara melakukannya sendiri.

10 - Pastikan lingkungan pengujian dan pengembangan Anda sangat mirip.

11 - Cobalah untuk mengidentifikasi dependensi utama (pada sistem lain atau antara komponen) yang tidak dapat dengan mudah terlihat.

12 - Identifikasi dan dokumentasikan versi yang diperlukan dari setiap penggunaan perangkat lunak dan kontak vendornya (jika perlu)

13 - Identifikasi setiap alat khusus yang ia gunakan yang tidak Anda miliki, kalau-kalau itu dapat membantu Anda.

14 - Dapatkan aliran sistem tingkat tinggi. dan mulai membangun perpustakaan dokumentasi Anda

15 - Memahami cara mengelola keamanan pengguna untuk aplikasi

16 - Dapatkan log bug dan cobalah untuk memahami tindakan dan bagaimana tindakan mempengaruhi data yang lebih lama (jika ada)

17 - Ketahui proses yang membutuhkan waktu terlalu lama dan apa yang perlu Anda perhatikan (misalnya ukuran file yang tidak biasa, ftp file duplikat, dll.) Di mana berlaku.

18 - Periksa jam server produksi

19 - Identifikasi letak konfigurasi dan bandingkan setiap konfigurasi lingkungan dengan produksi untuk mengetahui parameter apa yang berbeda dan mengapa

20 - Dapatkan informasi kontak orang ini

21 - Jika sistem internal, jadwalkan pertemuan dengan pengguna sistem (Anda perlu tahu siapa mereka dan apa peran yang dimainkan masing-masing) dan diperkenalkan kepada mereka. Dengarkan apa yang mereka katakan tentang sistem dan tentang masalah mereka saat ini jika ada. Pastikan Anda dimasukkan dalam email sedini mungkin (setelah persetujuan manajer Anda)

22 - Nilai pemahaman Anda 1 minggu sebelum dia pergi dan melaporkan setiap masalah yang Anda lihat sebagai risiko

Karena Anda menyebutkan Anda tidak memiliki database, daftar ini menjadi lebih pendek.

Semoga berhasil.

Tidak mungkin
sumber
@ Samra: Terima kasih atas komentar yang mengangkat. Saya membutuhkannya. :)
NoChance
Sangat lengkap dan mencakup beberapa poin penting yang mungkin saya lewatkan, misalnya melibatkan manajemen dan pelanggan (internal) kami.
PersonalNexus
5

Saya akan mempertimbangkan bagian yang paling rumit, dioptimalkan untuk kinerja terlebih dahulu. Saya akan meminta dia untuk mendokumentasikan bagian-bagian itu dan menjelaskannya kepada Anda satu per satu, kemudian saya akan mencoba untuk menulis tes terhadap bagian-bagian tersebut (termasuk sebelum dan sesudah pengujian kinerja, sehingga Anda dapat melihat apakah optimasi baru membuat semuanya lebih baik atau lebih buruk ) dan minta orang lain untuk meninjau tes. Dengan cara ini, dia mendokumentasikan dan menjelaskan, Anda menggunakan penjelasan untuk menulis tes (saat dia mendokumentasikan bidang yang berbeda), dan ulasannya akan membantu memastikan Anda memahami apa yang seharusnya Anda uji. Dengan cara itu Anda juga mendapatkan tambahan pengujian tambahan untuk beberapa bagian paling kritis dari aplikasi dan dokumentasi optimasi kinerja khusus.

Jika ada waktu setelah membahasnya, selanjutnya saya akan melalui proses serupa dengan bagian-bagian dari aplikasi yang paling sering membutuhkan perubahan selama bertahun-tahun tetapi yang tidak termasuk dalam kelompok hal pertama yang didokumentasikan.

Kemudian dokumentasikan apa pun yang tersisa.

HLGEM
sumber
5

Saya pikir cara terbaik untuk grok beberapa kode besar adalah pendekatan top-down. Cobalah untuk memahami gambaran besar terlebih dahulu, dan kemudian secara bertahap menggali lebih dalam komponen satu per satu.

Sekarang di setiap tingkat penggalian, minta dia untuk memprioritaskan bagian yang paling membutuhkan perhatian. Mintalah dia menjelaskan sebanyak mungkin, tetapi selalu dokumentasikan sendiri.

Bagian terbaik tentang mendokumentasikannya sendiri adalah bahwa ketika Anda akan kembali lagi nanti, Anda tidak akan memiliki masalah mengingat kembali kondisi kognitif yang sama seperti ketika Anda menjelaskannya kepada Anda. Anda bisa lebih mudah memahami apa yang Anda tulis daripada apa yang dilakukan orang lain. Dalam pengalaman saya, dua orang yang mendokumentasikan kode yang sama tidak menghasilkan teks yang mirip.

Ini, saya kira juga memecahkan masalah "apa & bagaimana cara mendokumentasikan" Anda. Ketika dia menjelaskan segalanya kepada Anda, Anda kemudian dapat memutuskan sendiri apa yang Anda inginkan didokumentasikan ketika Anda kembali ke kode - dan hanya mendokumentasikan bagian-bagian itu.

Idenya adalah untuk pertama benar-benar memahami kode (di hadapannya), dan kemudian menulis / melakukan segala sesuatu yang akan memungkinkan Anda untuk grok nanti (tanpa dia).

Dengan memahami sepenuhnya kode yang saya maksud, Anda perlu merasakan gambaran besarnya - dan bagaimana setiap komponen berhubungan dengan gambaran besar ini. Saya merasa sangat membantu untuk melacak bagaimana setiap bagian menambah keseluruhan. Jangan mencoba memahami apa pun secara terpisah - jangan pernah kehilangan konteksnya.

Terakhir, setelah Anda melakukan hal di atas, secara proaktif mengambil kendali. Tentukan sendiri bagian mana yang Anda butuhkan untuk uji unit. bagian mana yang perlu (atau bisa) dioptimalkan, bagaimana Anda bisa memperbaiki beberapa komponen, dll. Percaya bahwa jika Anda tahu sistemnya, Anda dapat mengambil semua keputusan begitu ia hilang.

treecoder
sumber
bagaimana Anda seharusnya mendokumentasikannya? teks biasa? wiki? komentar dalam kode sumber?
c69
Apa pun yang memungkinkan untuk mengembalikan pemahaman yang sama tentang kode yang Anda miliki ketika Anda menulis dokumen.
treecoder
5

Aku merasakan untukmu

Beberapa saran:

  1. Rekam setiap percakapan Anda dengan programmer yang pergi!
  2. Mintalah motivasi di balik masalah "besar". Ada baiknya Anda memahami API, tetapi gali untuk keputusan internal - mengapa kode itu dipartisi? apa saja tanggung jawabnya.
  3. Berusahalah untuk benar-benar mempelajari kode tersebut. Ketika Anda memikul tugas pemeliharaan dan dukungan terkadang ada tekanan untuk "mempelajari kode sambil membuat kemajuan". Tahan jika Anda bisa, dan pelajari kodenya dengan sungguh-sungguh.
  4. Cari skenario. Anda tahu API - lihat bagaimana kode berperilaku. Contoh yang terlintas dalam pikiran adalah modul Fax. Sebagai pengguna API, Anda preheps harus menyiapkan gambar halaman dan mengirim kode perintah untuk mengirimkan halaman. Mintalah programmer yang meninggalkan untuk melacak dengan Anda pada kode untuk melihat bagaimana skenario ini berjalan. Kemudian, tentu saja, masuk skenario "halaman penerima".
  5. 80/20 - cobalah untuk membahas skenario yang lebih umum terlebih dahulu.
  6. Pertimbangkan menulis ulang. Jika kodenya sudah tua dan antarmuka didefinisikan dengan baik, mungkin teknologi telah berubah cukup untuk membenarkannya.
  7. Saya benci mengatakan ini, tetapi pertimbangkan mencari pekerjaan baru.

sumber
Saya suka ide merekam setiap percakapan, sehingga saya bisa kembali ke kata-kata aslinya, setelah dia pergi. Saran # 7, namun, bukan pilihan ;-)
PersonalNexus
3

Jika Anda ingin dokumentasi yang layak cukup tanpa rasa sakit membeli salinan Pascal Analyzer (PAL) Saya telah menggunakan ini pada proyek Delphi dan itu hebat - mereka sekarang mungkin membagi fungsionalitas dokumentasi menjadi produk yang saya tidak kenal (Pascal Browser) jadi Anda mungkin harus membeli keduanya (<300 USD) tetapi PAL adalah alat yang hebat untuk memahami di mana variabel digunakan di mana fungsi dipanggil dari dll. & mengambil segala macam masalah potensial dengan kode.

Gunakan PAL untuk mendapatkan ide tentang bagaimana kode terstruktur plus mungkin daftar sekitar 1000 perbaikan yang disarankan jika pengalaman saya adalah sesuatu yang harus dilakukan. Bekerja melalui daftar akan meningkatkan kualitas kode, sangat menyederhanakan & membuat hidup Anda lebih mudah untuk masa depan. Delphi sendiri mendukung refactoring dalam versi terbaru (sekitar 5 tahun terakhir). Anda memang perlu memasukkan semua yang ada di file dpr agar benar-benar berfungsi dengan baik ketika saya melakukannya, ingatlah itu.

Jika Anda ingin pengujian unit, unduh DUnit & mulai buat beberapa tes dengan pembuat kode asli - itu mungkin cara konstruktif untuk menggunakan setidaknya sebagian dari waktu mereka.

mcottle
sumber
2

Meskipun Anda belum menyebutkan tentang database backend tetapi dengan asumsi ada satu Anda harus

  1. Dapatkan model data yang didokumentasikan terutama kolom dan PK-FK
  2. Siapkan jejak sql dan catat semua kueri yang diaktifkan saat menggunakan aplikasi. Urutan eksekusi kueri akan memberi Anda ide bagus tentang aliran aplikasi dan juga membantu dalam debugging
NRS
sumber
Poin bagus secara umum, tetapi tidak ada database dalam kasus khusus saya.
PersonalNexus
1
mungkin itu akan membantu orang lain
NRS
2

Saya berada dalam situasi yang sama ketika Arsitek kami pindah ke Australia dan meninggalkan banyak warisan ketika ia bersama perusahaan dari 8 tahun terakhir. Dia sendiri mewarisi barang warisan dari Arsitek sebelumnya yang merupakan kontraktor.

Anda dan orang lain telah menyebutkan poin yang baik tetapi di sini ada masalah yang kami hadapi setelah dia pergi mungkin Anda bisa mempersiapkan diri lebih baik ...

1) (Tenaga Teknis) Detail kontak pelanggan yang dihadapinya.

2) Akunnya di mana ia membeli lisensi perangkat lunak, kunci yang perlu diperbarui setiap tahun dan proses / biaya untuk memperbaruinya.

3) Dokumen Pengaturan pustaka / komponen perangkat lunak pihak ketiga dan produk yang terintegrasi dengan produk Anda. Kami berjuang selama 4 hari untuk membawa kembali mesin yang hilang karena IT membersihkan ruang dan beberapa instruksi yang salah diberikan kepada mereka.

4) Dokumen / langkah-langkah yang digunakannya untuk menyimpan kode sumber ke perangkat lunak Perusahaan penyimpanan misalnya Escrow.

5) Masih ada daftar panjang tapi mungkin tidak berlaku untuk Anda juga. Tidak ada jumlah dokumentasi yang dapat menggantikan orang sungguhan, jadi pertahankan detailnya, tetap dalam kondisi yang baik dan semoga sukses :)

Saya juga tidak tahu apakah ini pertama kalinya untuk Anda. Bagi saya, saya telah bekerja dengan 5/6 perusahaan dan selalu mewarisi kode dengan dokumentasi yang buruk atau tanpa dokumentasi sama sekali. Jadi, bersama dengan semua dokumentasi, tetap positif :)

Surjit Samra
sumber