Mengapa salah mengomentari kode dan kemudian secara bertahap menghapusnya untuk melacak apa yang telah saya lakukan dan apa yang masih harus dilakukan?

Setiap kali saya mengetahui bahwa sebagian besar kode saya perlu diubah, baik karena itu tidak benar atau karena perlu disesuaikan dengan perubahan arsitektur utama yang diperlukan oleh alasan lain, inilah yang biasanya saya lakukan:

1. Saya berkomentar semua kode yang saya curigai mungkin harus saya ubah. Saya memperlakukan kode yang dikomentari sebagai semacam daftar TODO saya.
2. Saya secara bertahap meninjau kode yang dikomentari dan menghapus tanda komentar bagian dari kode ini, atau menyalin-menempelnya di tempat lain dan kemudian mengeditnya seperlunya, atau menulis ulang bagian-bagian dari kode ini dari awal, melihat kode komentar untuk referensi. Setiap kali saya pikir saya sudah selesai dengan bagian dari kode berkomentar saya menghapusnya.
3. Saya melanjutkan ini sampai saya tidak dapat melihat lagi kode komentar.

Saya harus mencatat bahwa saya sebagian besar melakukan ini pada proyek pribadi yang saya kembangkan sendiri.

Namun, saya diberitahu, bahwa saya harus berhenti melakukan ini. Saya diberitahu bahwa alih-alih, saya harus mulai menggunakan git, merujuk pada commit lama untuk melihat kode lama, alih-alih meninggalkan kode yang dikomentari. Saya diberitahu:

Mengomentari kode adalah kebiasaan buruk yang harus dihapuskan. Anda kurang pengalaman sehingga Anda gagal memahaminya. Jika, dalam beberapa tahun, Anda melihat kode orang lain yang suka berkomentar kode, Anda sendiri akan mulai bersumpah pada orang ini. Setiap kali saya melihat kode berkomentar, saya menghapusnya secara keseluruhan, bahkan tanpa melihatnya, karena biasanya kode seperti itu sama sekali tidak berharga. Anda pasti akan gagal melihat kelemahan dari mengomentari kode dalam proyek kecil, satu orang; tetapi jika Anda menemukan pekerjaan dan mempertahankan kebiasaan ini, itu akan memalukan.

Bolehkah saya bertanya apa kelemahan ini dari apa yang saya lakukan sehingga saya gagal melihat sekarang?

Saya harus mengatakan saya tidak benar-benar tertarik hanya menggunakan git untuk melihat kode terakhir. Seperti yang saya katakan, saya memperlakukan kode komentar sebagai semacam todo-list; sementara git akan menunjukkan kepada saya bagaimana kode yang digunakan untuk mencari, itu akan gagal menunjukkan dengan jelas kepada saya bagian mana dari kode yang masih perlu ditinjau dan yang sudah dilakukan. Saya khawatir saya mungkin kehilangan beberapa bagian dari kode dan memperkenalkan bug.

Untuk kelengkapan, saya merasa saya harus menambahkan bahwa orang yang saya kutip adalah pengembang yang berpengalaman dan penggemar "Kode Bersih" Paman Bob - dan Paman Bob memang mengkritik berkomentar keras tentang kode dalam bukunya.

Jika pada akhirnya Anda menghapus semua kode yang dikomentari, saya tidak melihat masalah nyata dengan ini. Meninggalkan kode yang dikomentari dalam basis kode Anda adalah praktik yang buruk, tetapi bukan itu yang Anda lakukan jika Anda mengerjakan semuanya dan menghilangkannya. Saya menduga orang yang Anda ajak bicara tidak mengerti proses yang Anda gunakan atau sedang dogmatis.

Pada kenyataannya, kode komentar tidak berbahaya. Masalahnya adalah itu berantakan dan membuatnya sulit dibaca. Ada dosa yang jauh lebih buruk tetapi itu adalah hal yang sangat sederhana untuk dihilangkan. Sebagai orang yang berkomentar kode, Anda berada di posisi terbaik untuk menentukan bahwa itu dapat dihapus sepenuhnya.

Banyak IDE dan editor kode memahami semacam sintaks 'TODO' dalam komentar. Ini adalah cara alternatif untuk menandai apa yang perlu diubah. Anda mungkin ingin mempertimbangkan ini karena memberi sedikit informasi lebih banyak tentang apa yang Anda pikirkan ketika Anda menandainya.

Pada akhirnya lakukan hal-hal dengan cara yang menghasilkan hasil terbaik untuk Anda. Bahkan jika ini adalah proyek tim, selama Anda menghapus semua kode yang dikomentari Anda tidak membebani orang lain.

Bolehkah saya bertanya apa kelemahan ini dari apa yang saya lakukan sehingga saya gagal melihat sekarang?

Boleh dibilang, tidak ada jika Anda bekerja sendirian dan tidak menggunakan kontrol versi dan merasa tidak apa-apa untuk melakukannya dengan cara ini.

Bahkan, tanpa kontrol versi, tidak masalah apa yang Anda lakukan pada titik "waktu" apa pun karena kode selalu menyatakan apa pun file saat ini "disimpan" seperti dalam sistem operasi.

Jika Anda menggunakan kontrol versi, dan Anda memiliki banyak komentar sebagai "daftar tugas" Anda, dan Anda memperbaiki beberapa dan menghapus komentar, kemudian ulangi, lalu ulangi dll ... Anda kemudian memiliki kode "sedang dalam proses" dan komentar tersimpan dalam riwayat revisi Anda. Ini tidak akan menjadi masalah jika Anda tidak perlu kembali ke komit lain atau bahkan "memilih cherry" nanti (mis. Ini adalah di mana Anda mengambil komit tertentu dan menariknya ke cabang lain untuk digunakan). Tetapi sebaliknya itu bisa menjadi masalah.

Bisa dibilang ini dapat dibandingkan dengan perangkat lunak "snap shot" perangkat keras, seperti Windows (Pemulihan). Jika diperlukan snapshot dengan virus di dalamnya, Anda membunuh virus, tetapi kemudian perlu memutar kembali, Anda dapat kembali ke titik di mana virus hadir lagi.

Pendekatan ini juga cenderung menjadi masalah ketika Anda menggunakan kontrol versi dan bekerja dengan pengembang lain, karena mereka harus melihat daftar todo Anda yang tidak ada gunanya bagi mereka. Bahkan, hanya kekacauan yang harus mereka abaikan dan atasi. Di tim kami, kami selalu menghapus semua komentar, seperti kode lama atau "catatan". Kecuali mereka berguna - namun ini sangat jarang karena kami memiliki dokumentasi untuk "cara kerjanya", dan perangkat lunak untuk melacak apa yang perlu dilakukan (alias todo).

Juga, ketika bekerja pada proyek yang lebih besar Anda cenderung berkolaborasi, dan berkomitmen dan mendorong sering, sehingga mungkin cabang mereka sedang mengerjakan memiliki daftar TODO Anda jika mereka menggabungkan cabang Anda ke mereka. Maka daftar TODO Anda adalah urusan semua orang: D

Singkatnya, jika Anda tidak bekerja sendirian dan terutama ketika menggunakan kontrol versi, itu mengacaukan sejarah dan dapat berantakan untuk pengembang lainnya.

Dan, ini adalah hal pribadi dalam beberapa hal, tetapi menggunakan basis kode sebagai "daftar agenda" Anda sebenarnya tidak ideal. Suatu hari Anda mungkin meninggalkan sesuatu secara tidak sengaja, atau lupa untuk berkomentar atau menghapus komentar itu karena kesalahan.

Seperti halnya banyak pendekatan untuk arsitektur, pengkodean, dan cara Anda secara pribadi atau tim Anda bekerja, setiap skenario dapat meminta sesuatu yang berbeda. Jadi pertimbangkan kelemahan yang disebutkan, dan manfaat menggunakan kontrol versi, dan putuskan apakah itu berfungsi untuk Anda .

Sepertinya resensi Anda sedikit dogmatis. Saya tidak yakin bersumpah pada seseorang untuk mengomentari kode adalah PC ;-), atau bahkan membantu ;-)

Tapi yang lebih serius, saya pikir resensi Anda benar, bahwa Anda harus serius mempertimbangkan menggunakan git (atau sistem kontrol sumber lain, tetapi git adalah pilihan yang masuk akal).

Dan hal itu dapat mengurangi sebagian kebutuhan Anda untuk mengomentari kode.

Tetapi memiliki daftar TODO dalam kode (apakah daftar berpoin atau kode lama) - cukup masuk akal menurut saya. Tetapi Anda mungkin ingin mempertimbangkan kembali sedikit tentang bagaimana Anda melakukannya. Untuk satu hal - saya sarankan memikirkan orang lain yang membaca kode Anda. Bahwa orang lain bisa jadi Anda, setahun setelah Anda drop dan bergabung kembali dengan proyek. Atau bisa juga orang lain sepenuhnya. HANYA menemukan kode komentar agak membingungkan. Mungkin sesuatu seperti:

/*
 * Need this sort of functionality added back before too long:
 * .... OLD CODE HERE
 */

Secara pribadi, saya lebih condong ke arah sesuatu seperti ini:

 * TODO:
 *      @todo   Possible get rid of intermediate LRUCache_ object.
 *
 *      @todo   Find some reasonable/simple way to get
 *              LRUCache<PHRShortcutSpec, PHRShortcutSpec, PHRShortcutSpecNoAuthCacheTraits_>   sRecentlyUsedCache (kMaxEltsInReceltlyUsedCache_);
 *              Working with ONE T argument
 *              Add(elt2cache).
 ...

dan saya merasa bebas untuk memasukkan 'cuplikan kode' dari kode lama sebagai hal yang bermanfaat.

Menggunakan git itu sulit (sedih). Anda perlu waktu untuk belajar, dan mungkin rasanya itu bukan bagian dari apa yang ingin Anda capai. Tetapi jika Anda ingin memprogram dengan berguna, Anda harus belajar untuk melakukannya sebagai bagian dari tim, dan berkomunikasi dengan tim, dan git adalah cara yang dilakukan saat ini. Dan setelah Anda menggunakannya, Anda akan menemukan itu alat / penopang SANGAT bermanfaat, membuat pengembangan perangkat lunak Anda lebih mudah.

Semoga berhasil!

Ada banyak alasan untuk berkomentar kode: -

• Itu belum benar, dan Anda akan berhenti berkomentar ketika sudah siap.
• Anda sementara berkomentar untuk mengubah perilaku saat debugging.
• Anda tidak yakin apakah kode itu diperlukan, tetapi tidak ingin menghapusnya sampai Anda menguji lagi.
• Kode diperlukan untuk beberapa versi perangkat lunak, tetapi tidak untuk yang ini.
• Kode ini sudah usang, tetapi butuh waktu lama untuk menulis dan Anda secara emosional terikat padanya. Selain itu, mungkin berguna suatu hari.

Masalahnya muncul ketika Anda meletakkan kode ke tempat tidur, lalu kembali lagi beberapa tahun kemudian untuk melakukan pemeliharaan. Anda akan menemukan basis kode yang dikotori dengan kode komentar. Tidak lagi jelas mengapa semua itu ada di sana, dan sekarang hanya berantakan.

Jika Anda menggunakan alat kontrol versi yang tidak layak, Anda dapat dengan berani menghapus kode yang tidak Anda perlukan lagi, aman karena mengetahui bahwa sistem kontrol versi masih menyimpannya. Perbedaan file antar versi akan mengungkapkan apa yang telah dihapus. Setelah Anda menerapkan kontrol versi, satu-satunya kebutuhan untuk berkomentar adalah untuk hal-hal sementara. Jika Anda pernah menemukan kode yang dikomentari dalam file yang sebenarnya tidak Anda kerjakan, Anda bisa menghapusnya.

Saya tidak akan mengulangi mengapa Anda harus menggunakan kontrol sumber bahkan untuk proyek satu orang, karena ada banyak sumber daya lain di luar sana yang akan memberitahu Anda untuk melakukan ini. Tetapi satu kelemahan utama yang terkait dari pendekatan Anda saat ini adalah bahwa jika Anda berkomentar kode, Anda menyembunyikannya dari IDE Anda (jika Anda tidak menggunakan IDE Anda mungkin harus mempertimbangkannya).

Misalnya, jika Anda ingin mengganti nama metode atau kelas, atau mengubah jumlah parameter yang digunakan metode, IDE Anda harus memiliki opsi refactor untuk melakukan ini yang akan menemukan semua referensi yang sesuai dan memperbaruinya sesuai - tetapi mungkin akan menang ' t mencari di komentar.

Alih-alih mencoba menebak di mana Anda perlu membuat perubahan, buat saja mereka dan biarkan IDE Anda memberi tahu Anda di mana perubahan Anda telah menyebabkan banyak hal rusak. Anda kemudian dapat berkomentar kode lebih pembedahan, dan mudah-mudahan untuk jangka waktu yang lebih singkat sebelum Anda memperbaiki apa pun yang rusak.

Ini buruk dan Anda harus berhenti .

Alasannya bermuara pada upaya untuk melakukan sejumlah besar refactoring dalam sekali jalan.

Jika Anda mengomentari sebagian besar kode, perbaiki sedikit dan check-in, maka Anda telah memeriksa dalam kode non-fungsional. dan banyak sekali komentar atas hal-hal yang akan dianggap orang lain sudah tua dan dapat diabaikan

Jika Anda tidak sering check-in, maka Anda mengumpulkan konflik gabungan dan tidak merekam kemajuan langkah demi langkah.

Anda perlu mengubah praktik kerja Anda sehingga jika Anda harus berhenti di tengah jalan semuanya masih berfungsi.

Ambil langkah kecil dan check in setelah masing-masing:

• ekstrak sebuah antarmuka
• tulis ujian
• refactor suatu fungsi

Jangan menandai bongkahan besar kode sebagai 'milikmu' dengan berkomentar dan membawanya pergi sendiri sampai mereka selesai atau kamu gagal.

Jika Anda perlu melacak apa yang perlu dilakukan, gunakan papan tugas seperti scrum atau trello