Apakah menyebarkan kode dengan komentar refactoring adalah ide yang bagus?

Saya sedang mengerjakan proyek "kode-spaghetti", dan sementara saya memperbaiki bug dan mengimplementasikan fitur-fitur baru, saya juga melakukan beberapa refactoring untuk membuat unit kode dapat diuji.

Kode sering kali sangat erat atau rumit sehingga memperbaiki bug kecil akan menghasilkan banyak kelas yang ditulis ulang. Jadi saya memutuskan untuk menarik garis di suatu tempat di dalam kode tempat saya berhenti refactoring. Untuk memperjelas ini, saya memberikan beberapa komentar dalam kode yang menjelaskan situasi, seperti:

class RefactoredClass {
    private SingletonClass xyz;

    // I know SingletonClass is a Singleton, so I would not need to pass it here.
    // However, I would like to get rid of it in the future, so it is passed as a
    // parameter here to make this change easier later.
    public RefactoredClass(SingletonClass xyz) {
        this.xyz = xyz;
    }
}

Atau, sepotong kue:

// This might be a good candidate to be refactored. The structure is like:
// Version String
//    |
//    +--> ...
//    |
//    +--> ...
//          |
//    ... and so on ...    
//
Map map = new HashMap<String, Map<String, Map<String, List<String>>>>();

Apakah ini ide yang bagus? Apa yang harus saya ingat ketika melakukannya?

refactoring comments

— Uooo
sumber

related / duplikat: Apakah komentar TODO masuk akal?

— nyamuk

Ini adalah topik berbasis opini; tapi pendapat pribadi saya adalah bahwa ini adalah persis jenis komentar yang berguna, dan bahwa saya berharap akan menemukan di kode orang lain: ia memberitahu Anda informasi penting yang belum jelas dari kode; bukan apa metode tidak, tetapi mengapa .

— Kilian Foth

HashMap <String, Map <String, Map <String, List <String>

— >>>

Komentar yang memberi tahu saya mengapa sepotong kode terlihat bau sangat dihargai. Saya mungkin tidak memiliki pemahaman Anda tentang basis kode, jadi saya hanya akan melihat masalah dan berpikir "Apa-apaan ini?", Tetapi komentar yang menjelaskan mengapa ini karena akan membantu saya berkeliling kode lebih cepat. Ya, sangat banyak melakukan ini. (Dengan asumsi Anda tidak dapat memperbaiki kode untuk tidak menjadi WTF, tentu saja!)

— Phoshi

Jawaban:

Apakah menyebarkan kode dengan komentar refactoring adalah ide yang bagus?

Jika Anda telah mengalokasikan waktu untuk menyelesaikan refactoring Anda, dan jika Anda benar-benar melakukannya, maka ya - itu akan berhasil.

Apa yang harus saya ingat ketika melakukannya?

IDE modern memiliki opsi untuk menemukan dan menampilkan garis TODO. Anda harus memeriksanya dari waktu ke waktu, dan mencoba mengurangi jumlahnya kapan pun Anda bisa.

— BЈовић
sumber

Saya akan membuat /// @todokomentar pertimbangan seperti itu untuk doxygen atau tag kustom yang mudah dipasang untuk javadoc , jadi itu akan secara otomatis diekstraksi ke bagian catatan dokumen API. Komentar polos akan diabaikan terlalu mudah dan akhirnya tersesat di kedalaman kode.

[Sunting] BTW: apakah ini ide yang bagus:

sementara saya memperbaiki bug dan mengimplementasikan fitur-fitur baru, saya juga melakukan beberapa refactoring untuk membuat kode unit dapat diuji

Saya pikir (tahu berdasarkan pengalaman!), Refactoring bisa sangat berbahaya, terutama ketika masih belum ada unit test. Jadi, Anda sebaiknya membatasi pekerjaan tambahan Anda (saat memperbaiki bug dll) untuk menambahkan komentar yang harus dilakukan ... Kita semua tahu: kapan saja;)

— Serigala
sumber

cuplikan kode dalam pertanyaan berbunyi seperti Java, mengapa Anda merekomendasikan Doxygen?

— nyamuk

Saya memang tahu bahwa doxygen mendukung @todo - untuk javadoc saya tidak yakin - tetapi apakah bahasanya sangat penting? Dari sudut pandang saya, contoh java menggambarkan masalah yang lebih dalam.

— Wolf

@gnat: Apakah menurut Anda lebih baik sekarang?

— Wolf