Rehat kopi #20. Apa itu kode lama dan cara menggunakannya. Alat yang memudahkan penulisan dokumentasi teknis

Apa itu kode lama dan cara menggunakannya

Sumber: Dou Cepat atau lambat, seorang programmer mungkin harus menemukan kode lama. Untuk meringankan konsekuensi dari perkenalan ini, saya telah memilih beberapa tips dan contoh praktis dari pengalaman saya sendiri - khususnya, bekerja dengan sistem Java yang lama.

Fitur Warisan

Warisan adalah kode orang lain, yang seringkali sangat buruk sehingga tidak jelas cara menggunakannya. Dan jika Anda harus bekerja dengan sistem lama, selain kode lama, Anda juga akan menemukan:

• dengan teknologi ketinggalan jaman;
• arsitektur heterogen;
• kurangnya atau bahkan tidak adanya dokumentasi sama sekali.

Faktanya, kode lama tidak terlalu menakutkan, dan inilah alasannya: jika sistem telah hidup selama sepuluh tahun ini dan masih berfungsi, maka kode tersebut ada gunanya. Mungkin ini menghasilkan banyak uang (tidak seperti startup terakhir Anda). Selain itu, kode ini relatif dapat diandalkan jika mampu bertahan dalam produksi selama ini. Oleh karena itu, perubahan terhadapnya harus dilakukan dengan hati-hati. Pertama-tama, Anda perlu memahami dua hal:

1. Kita tidak bisa meremehkan sistem yang menghasilkan jutaan atau diakses oleh ribuan orang setiap hari. Tidak peduli seberapa buruk penulisannya, kode menjijikkan ini tetap bertahan hingga produksi dan bekerja 24/7.

2. Karena sistem ini menghasilkan uang nyata, bekerja dengannya memiliki tanggung jawab yang besar. Ini bukan startup, tapi sesuatu yang akan dikerjakan pengguna besok. Hal ini juga berarti biaya kesalahan yang sangat tinggi, dan intinya di sini bukan pada klaim klien, namun pada keadaan sebenarnya.

Rekayasa terbalik

Agar berhasil bekerja dengan kode lama, Anda harus menggunakan teknik rekayasa terbalik. Pertama, Anda perlu membaca kode dengan cermat untuk memahami cara kerjanya. Ini wajib karena kemungkinan besar kami tidak memiliki dokumentasi. Jika kita tidak memahami alur pemikiran penulis, kita akan melakukan perubahan dengan konsekuensi yang tidak dapat diprediksi. Untuk melindungi diri Anda dari hal ini, Anda juga perlu mempelajari kode berikutnya. Dan pada saat yang sama bergerak tidak hanya secara luas, tetapi juga secara mendalam. Di mana metode yang dipanggil dengan kesalahan? Kode pemanggilnya dari mana? Dalam proyek lama, "hierarki panggilan" dan "hierarki tipe" lebih sering digunakan daripada apa pun. Anda harus menghabiskan banyak waktu dengan debugger: pertama, untuk menemukan kesalahan, dan kedua, untuk memahami cara kerja semuanya. Mengenai dokumentasi, bukanlah ide yang buruk untuk menggunakan arkeologi industri. Akan sangat berguna untuk menggali dokumentasi lama di suatu tempat dan berbicara dengan mereka yang mengingat bagaimana kode yang Anda warisi ditulis. Dengan menggunakan teknik ini, cepat atau lambat Anda akan mulai memahami kodenya. Namun agar usaha Anda tidak sia-sia, Anda harus segera mendokumentasikan hasil penelitian Anda. Untuk melakukan ini, saya sarankan menggambar diagram blok atau diagram urutan. Tentu saja Anda akan malas, tetapi Anda pasti perlu melakukan ini, jika tidak dalam enam bulan tanpa dokumentasi Anda akan menggali kode ini seperti pertama kali.

Jangan menulis ulang kodenya

Hal terpenting dalam proses pengembangan adalah menyalahkan diri sendiri tepat waktu dan tidak mencoba menulis ulang seluruh kode dari awal. Perkirakan berapa tahun kerja yang dibutuhkan. Kecil kemungkinannya pelanggan ingin menghabiskan begitu banyak uang untuk mengulang sesuatu yang sudah berhasil. Hal ini tidak hanya berlaku pada sistem secara keseluruhan, namun juga pada bagian mana pun dari sistem tersebut. Tentu saja, mereka mungkin memberi Anda waktu seminggu untuk memikirkan semuanya, dan satu minggu lagi untuk memperbaiki sesuatu. Namun kemungkinan besar mereka tidak akan memberi Anda waktu dua bulan untuk menulis kembali bagian dari sistem tersebut. Sebagai gantinya, terapkan fungsionalitas baru dengan gaya yang sama seperti kode lainnya. Dengan kata lain, jika kodenya sudah lama, Anda tidak boleh tergoda untuk menggunakan teknologi baru yang cantik: kode tersebut akan sangat sulit dibaca. Misalnya, Anda mungkin menghadapi situasi seperti yang kita alami: sebagian sistem ditulis dalam Spring MVC, dan sebagian lagi ditulis dalam servlet kosong. Dan jika di bagian yang ditulis di servlet, ada hal lain yang perlu ditambahkan, maka kita menambahkannya dengan cara yang sama - di servlet.

Hormati kepentingan bisnis

Harus diingat bahwa setiap tugas ditentukan, pertama-tama, oleh nilai bagi bisnis. Jika Anda tidak membuktikan kepada pelanggan perlunya perubahan tertentu dari sudut pandang bisnis, perubahan tersebut tidak akan terjadi. Dan untuk meyakinkan pelanggan, Anda harus berusaha berdiri di tempatnya dan memahami kepentingannya. Khususnya, jika Anda ingin melakukan refactor hanya karena kodenya sulit dibaca, Anda tidak akan diizinkan melakukannya, dan Anda harus menjalaninya. Jika Anda benar-benar tidak tahan, Anda dapat mengatur ulang kode secara diam-diam dan sedikit demi sedikit, menyebarkan pekerjaan ke seluruh tiket bisnis. Atau meyakinkan pelanggan bahwa hal ini, misalnya, akan mengurangi waktu yang diperlukan untuk menemukan kesalahan, dan pada akhirnya mengurangi biaya.

Tes

Jelas bahwa pengujian diperlukan dalam proyek apa pun. Namun ketika bekerja dengan sistem lama, perhatian khusus harus diberikan pada pengujian juga karena dampak perubahan yang dilakukan tidak selalu dapat diprediksi. Anda memerlukan penguji setidaknya sebanyak pengembang, jika tidak, Anda harus sangat ahli dalam otomatisasi. Dalam proyek kami, pengujian terdiri dari tahapan berikut:

1. Verifikasi, ketika fungsionalitas fitur yang diimplementasikan diperiksa di cabang terpisah.
2. Stabilisasi, ketika cabang rilis diperiksa di mana semua fitur digabungkan.
3. Sertifikasi, ketika hal yang sama dijalankan kembali pada kasus pengujian yang sedikit berbeda dalam lingkungan sertifikasi yang sedekat mungkin dengan produksi dalam hal karakteristik dan konfigurasi perangkat keras.

Dan hanya setelah melalui ketiga fase ini barulah kita bisa melakukan rilis. Seseorang mungkin berpikir bahwa sertifikasi adalah fase tambahan, karena semuanya telah diklarifikasi pada tahap stabilisasi, tetapi pengalaman kami menunjukkan bahwa ini tidak benar: terkadang selama uji regresi, yang dijalankan untuk putaran kedua di komputer lain, sesuatu entah bagaimana itu akan keluar.

Formalisasikan DevOps dan Rilis

Prosedur pelepasannya, misalnya, adalah sebagai berikut. Ketika pengembangan selesai dan dua atau tiga fase pengujian telah diselesaikan, kami menulis email ke tim DevOps 36 jam sebelum perkiraan waktu rilis. Setelah ini, kami memanggil tim devops dan mendiskusikan semua perubahan di lingkungan (kami memberi tahu mereka tentang semua perubahan dalam database dan konfigurasi). Untuk setiap perubahan kami memiliki dokumen (tiket di Jira). Kemudian, selama rilis, semua orang yang terlibat dalam hal ini berkumpul, dan semua orang mengatakan apa yang mereka lakukan sekarang: “Kami mengunggah database”, “Kami memulai ulang server ini dan itu”, “Kami menjalankan uji regresi di lingkungan produksi. ” Jika terjadi kesalahan, prosedur rollback rilis diluncurkan, persis seperti yang dijelaskan dalam dokumen rilis asli - tanpa dokumen seperti itu kita pasti akan melupakan sesuatu atau bingung.

Kontrol kualitas kode

Dan terakhir, peninjauan kode adalah praktik yang karena alasan tertentu tidak digunakan di semua proyek. Sangat bagus jika setiap bagian kode ditinjau oleh lebih dari satu orang. Bahkan dalam tim yang sangat kuat, beberapa bug selalu ditemukan selama proses peninjauan kode, dan jika beberapa orang melihatnya, jumlah bug yang teridentifikasi bertambah. Apalagi terkadang reviewer ketiga atau keempat menemukan hal terburuk.

Alat yang memudahkan penulisan dokumentasi teknis

Sumber: Dzone Kebanyakan programmer tidak suka menulis dokumentasi teknis. Pakar psikologi Gerald Weinberg bahkan menyebut dokumentasi sebagai “minyak jarak dari pemrograman”: pengembang suka membacanya, tetapi mereka benci menulisnya sendiri. Kurangnya panduan atau peta jalan yang kosong mengakibatkan kurangnya informasi tentang cara kerja berbagai bagian perangkat lunak. Hal ini pada akhirnya memperburuk pengalaman pengguna akhir kode karena, tanpa adanya dokumentasi, mereka tidak dapat mengandalkan keakuratan dan kegunaan produk. Untuk memudahkan pemrogram membentuk kebiasaan menulis dokumentasi, saya sarankan untuk memperhatikan empat alat luar biasa yang kini tersedia untuk hampir semua orang.

Halaman GitHub

Mungkin tidak ada satu pun pengembang saat ini yang tidak memiliki pengalaman bekerja di GitHub. Ini juga merupakan tempat yang bagus bagi programmer yang membutuhkan tempat untuk menyimpan dokumentasi. Banyak orang menggunakan Readme standar dalam basis kode mereka untuk memberikan panduan cara kerja yang sederhana kepada pengguna, tetapi ini bukan satu-satunya cara untuk membuat dokumentasi di GitHub. Dengan GitHub Pages , Anda mendapatkan lebih dari sekedar hosting untuk halaman proyek Anda, termasuk dokumentasi dan tutorial. Anda mendapatkan kemampuan untuk berinteraksi langsung dengan semua repositori GitHub, memungkinkan pengembang memperbarui dokumentasi dengan cara yang sama seperti mereka memperbarui kodenya. Selain itu, Anda dapat menggunakan Jekyll di sini - ini membantu Anda mengubah markup Anda menjadi teks biasa atau menjadi halaman web lengkap.

Baca Dokumen

Seperti namanya, Read the Docs menyediakan platform bagi pengembang untuk menyimpan dan membaca dokumentasi. Layanan ini bekerja seperti Halaman GitHub: pemrogram dapat membuat perubahan pada dokumentasi dari sistem kontrol versi favorit mereka, termasuk Git, Bazaar, Mercurial, dan lainnya. Pembuatan versi otomatis dan pembuatan halaman juga didukung. Bagian terbaik dari Read Docs adalah fleksibilitasnya. Ini mendukung webhook sehingga Anda dapat mengotomatiskan sebagian besar proses pembuatan dokumen. Ini adalah penghemat waktu yang sangat besar untuk tugas yang tidak ingin dilakukan oleh sebagian besar pemrogram. Selain itu, semua yang dihosting di platform ini tersedia untuk masyarakat umum dalam berbagai format, termasuk PDF, HTML satu halaman, dan bahkan format e-book. Layanan ini mengambil bagian penting dari pekerjaan rutin untuk menjaga dokumentasi tetap terkini.

Tetra

Tettra bukan hanya sebuah platform untuk menyimpan dokumentasi perangkat lunak, tetapi basis pengetahuan yang lengkap. Ini bekerja dengan baik terutama ketika sebuah proyek melibatkan sekelompok besar pembuat kode yang mengerjakan berbagai perangkat lunak. Tettra dapat digunakan untuk mendokumentasikan jawaban atas pertanyaan umum.

Tempat pemeliharaan lebah

Apa yang membuat Apiary sangat berguna bagi pengembang adalah fakta bahwa Apiary berfungsi dengan baik dalam membantu dokumentasi API. Platform ini memungkinkan pengguna untuk menulis dokumentasi mereka di Markdown , termasuk panggilan API tiruan. Peternakan lebah juga memungkinkan Anda menguji dan membuat prototipe elemen API. Dengan kata lain, ini adalah alat dokumentasi dan platform pengujian di satu tempat.