Apakah komentar TODO masuk akal? [Tutup]

Saya mengerjakan proyek yang cukup besar dan mendapat tugas untuk melakukan beberapa terjemahan untuknya. Ada banyak label yang belum diterjemahkan dan ketika saya sedang menggali kode, saya menemukan sepotong kode ini

//TODO translations

Ini membuat saya berpikir tentang arti dari komentar-komentar ini untuk diri Anda sendiri (dan yang lainnya?) Karena saya merasa bahwa sebagian besar pengembang setelah mereka menyelesaikan kode tertentu dan melakukan apa yang seharusnya dilakukan mereka tidak pernah melihat ini sampai mereka memiliki untuk mempertahankannya atau menambahkan fungsionalitas baru. Sehingga ini TODOakan hilang untuk waktu yang lama.

Apakah masuk akal untuk menulis komentar ini atau haruskah itu ditulis di papan tulis / kertas / sesuatu yang lain di mana mereka tetap menjadi fokus pengembang?

Saya cenderung menggunakan // todokomentar untuk hal-hal yang harus terjadi, tetapi saya tidak bisa segera melakukannya.

Saya juga memastikan bahwa saya mengejar mereka - saya mencarinya (Visual Studio memiliki fitur yang bagus di mana ia akan mencantumkan komentar tersebut untuk Anda) dan memastikan bahwa semuanya sudah selesai.

Tetapi, seperti yang Anda katakan, tidak semua orang rajin tentang mereka dan seperti banyak komentar, mereka cenderung membusuk dari waktu ke waktu.

Saya akan mengatakan ini lebih merupakan preferensi pribadi - selama Anda mendokumentasikan apa yang perlu dilakukan dan mengejar itu, tidak masalah apakah itu dalam // todo, catatan postit atau papan tulis (di mana mereka juga bisa berakhir tidak sedang ditindaklanjuti).

IDE modern mengenali TODOkomentar dan mereka terlihat seperti itu di panel / jendela / tab mereka sendiri, sehingga mereka secara teoritis tidak hilang (saya berpikir Eclipse dan Visual Studio, keduanya saya cukup tahu untuk mengingat bahwa mereka mengenalinya).

Anda bahkan dapat mengonfigurasi kata-kata komentar tambahan seperti FIXME, BEWAREatau apa pun yang ingin Anda sesuaikan. Namun, pengembang lain di proyek Anda harus menyesuaikan IDE mereka dengan cara yang sama.

Sekarang, saya menulis "secara teoritis" karena meskipun tidak hilang, TODO lebih dari sering berhubungan dengan sesuatu yang tidak diperlukan agar aplikasi berfungsi dengan baik "saat ini". Dan "saat ini" dapat berlangsung selama 5 menit hingga 5 tahun, tergantung pada jenis / ukuran proyek :-)

Akhirnya, menurut pendapat saya, masih lebih masuk akal untuk memasukkannya ke dalam kode, di tempat yang tepat, tepatnya menjawab pertanyaan "di mana saya harus melakukan perubahan" daripada di tempat lain di luar kode.

Sunting: Seperti yang ditulis dalam artikel Wikipedia tentang komentar , termasuk tanggal dan pemilik TODO dianggap sebagai praktik yang baik.

Mungkin masuk akal, setidaknya saya kadang menggunakannya. Poin kuncinya adalah menggunakan tag yang konsisten seperti TODOatau FIXMEagar mereka dapat dengan mudah ditemukan dengan pencarian teks sederhana.

Misalnya, solusi "cepat dan kotor" mudah untuk diberi label, seperti:

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

Jika kode melakukan apa yang seharusnya dilakukan, dan tidak ada yang mengeluh, maka komentar tidak ada salahnya. Jika ada waktu untuk mempercantik kode, mudah untuk memulai dengan mencari FIXMElabel.

Di industri saya, pengembang didorong untuk membuat entri JIRA (atau dll) alih-alih menulis komentar karena tidak semua orang mendapat kesempatan untuk melihat // todoentri tersebut. Tetapi kadang-kadang dalam proyek besar atribut kustom didefinisikan di sepanjang baris:

[AttributeUsageAttribute(AttributeTargets.All, AllowMultiple = true)]
public class DeveloperNote : Attribute
{
    public DateTime EntryDate { get; set; }
    public string Description { get; set; }
    public DeveloperNote(int year, int month, int day, string desc)
    {
        EntryDate = new DateTime(year, month, day);
        Description = desc;
    }
}

Dan kemudian suatu metode dapat didekorasi dengan cara ini ...

[DeveloperNote(2011, 12, 13, "Make the db connection configurable")]

Dan petinggi dapat datang dan memanen ini secara otomatis. Ini mungkin berlebihan untuk // todopengingat sederhana , tetapi efektif. Juga membutuhkan platform .NET.

TODO hanyalah sebagian kecil dari komentar. Komentar memiliki kegunaan yang besar jika penulis sama sekali ahli dalam mengetahui apa yang harus disampaikan dan bagaimana menyampaikannya. Rasa humor juga dapat diterapkan di sini dalam dosis kecil untuk menyenangkan pemelihara bertahun-tahun kemudian.

Saya mendapat telepon tahun lalu bahwa beberapa kode saya sudah pensiun. Saya agak terkesan bahwa itu sudah dalam produksi dan bertahan pemeliharaan selama 16 tahun. Jadi berhati-hatilah, kode Anda bisa bertahan lama. Mengomentari niat, kebutuhan masa depan, dan sebagainya dapat sangat membantu seseorang bertahun-tahun dari sekarang yang melihat kode Anda untuk pertama kalinya.

Dalam pengalaman saya itu tergantung. Faktor utama adalah apakah tim cukup disiplin untuk menindaklanjuti komentar "kecil" ini. Jika ya maka mereka masuk akal. Jika tidak, komentar ini hanya buang-buang waktu dan Anda mungkin ingin melihat opsi lain, misalnya kartu cerita.

Secara pribadi saya menggunakan komentar TODO sesekali tetapi mereka biasanya hanya berumur pendek dan saya biasanya hanya memiliki sejumlah kecil dari mereka seperti satu, dua atau tiga. Saya menggunakannya lebih sebagai penanda di basis kode daripada apa pun. Jika saya menunggu terlalu lama untuk merawat mereka maka saya lupa tentang apa yang saya pikir perlu saya 'lakukan'.

Preferensi saya akan selalu tidak menggunakan ini dan sebaliknya menggunakan kartu cerita yang tepat atau simpanan atau sejenisnya. Gunakan satu mekanisme untuk satu tugas.

Saya dulu menulisnya di masa lalu, tetapi saya menemukan bahwa Anda biasanya tidak menindaklanjutinya.

Karena itu sekarang saya hanya menggunakannya untuk menandai hal-hal yang ingin saya kerjakan segera setelah saya menyelesaikan apa yang saya sibuk. Misalnya, saya menerapkan fungsi baru dan perhatikan bahwa fungsi yang saya gunakan memiliki bug kecil; Saya membuat FIXME untuk memperbaikinya agar tidak tergelincir dalam tugas saya saat ini.

Untuk membantu saya, build CI kami diatur untuk gagal jika ada FIXME dalam kode :-).

Jika Anda melihat masalah potensial yang tidak dapat diatasi segera, buka tiket / bug / masalah untuk mereka. Dengan begitu, mereka dapat diprioritaskan seperti semua bug. Saya merasa ini jauh lebih baik daripada memiliki beberapa masalah dalam bug DB dan beberapa dalam kode sebagai TODO.

Secara opsional, Anda dapat memasukkan TODO dengan ID bug :-).

Saya pikir TODOkomentar, sampai batas tertentu, masuk akal. Terutama jika Anda bekerja iteratif (seperti umum di lincah dan TDD toko), akan ada hal-hal yang Anda mengakui sedang akan diperlukan sebelum panjang tetapi yang Anda tidak ingin membuat jalan memutar untuk melaksanakan saat itu juga.

Yang menjadi jelek adalah ketika komentar seperti itu tetap berada dalam basis kode. Saat Anda secara aktif mengerjakan fitur, tidak masalah untuk membiarkannya masuk, tetapi begitu Anda semakin dekat untuk menyelesaikan fitur, Anda harus fokus untuk menyingkirkannya. Jika Anda tidak ingin melakukan pekerjaan untuk benar-benar menggantinya dengan kode yang benar dan berfungsi, maka, paling tidak faktor fungsionalitas yang relevan. Untuk meminjam contoh @ JoonasPulakka, di mana kode awalnya mengatakan

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

Anda mungkin mengubahnya menjadi sesuatu seperti

ConnManager.getConnection(GetDatabaseName());

dengan, untuk saat ini, GetDatabaseName () menjadi sebuah rintisan yang hanya mengembalikan string yang sama dengan yang Anda mulai. Dengan begitu, ada titik jelas ekspansi di masa depan, dan Anda tahu bahwa setiap perubahan yang dibuat di sana akan tercermin di mana pun nama database diperlukan. Jika nama database bahkan cukup umum, ini bisa menjadi peningkatan besar dalam pemeliharaan.

Secara pribadi, saya menggunakan kata kunci saya sendiri, bukannya ketat TODO, meskipun tujuannya sama: untuk menandai hal-hal yang saya tahu perlu ditinjau kembali. Juga, sebelum saya memeriksa kode saya, saya melakukan pencarian kode sumber global untuk kata kunci itu, yang dipilih sedemikian rupa sehingga biasanya tidak akan muncul di mana pun dalam kode. Jika ditemukan, saya tahu saya lupa sesuatu, dan dapat melanjutkan dan memperbaikinya.

Adapun menyertakan nama programmer / tanda tangan dengan komentar, saya pikir itu berlebihan jika Anda memiliki sistem kontrol versi kode sumber (Anda melakukannya , kan?). Dalam hal ini, fitur menyalahkannya akan memberi tahu Anda siapa yang menambahkan komentar, atau lebih tepatnya siapa yang terakhir memeriksa perubahan yang menyentuh komentar. Misalnya, dalam Visual Studio, ini mudah dilakukan dengan menggunakan fitur "Annotate" yang ditemukan di antara fitur kontrol sumber.

Jika Anda menulis TODO atau FIXME dengan gagasan bahwa orang lain akan memperbaikinya ketika mereka datang ke kode itu di masa depan yang tidak pasti maka saya akan mengatakan jangan repot-repot. Mereka akan membuang kode dan mengacaukan bagian pelaporan IDE Anda yang mengumpulkan informasi ini.

Agar bermanfaat, mereka harus menyediakan sarana untuk menandai kode Anda untuk waktu yang sangat dekat sehingga Anda dapat kembali ke keadaan pikiran yang tepat dengan lebih cepat. Dengan kata lain, Anda menempatkannya dalam kode Anda hanya untuk menghapusnya ASAP.

Apa pun yang berumur lebih lama sebenarnya harus ditempatkan di basis bug Anda di mana tempatnya.

Ada cukup banyak kebisingan dalam hidup kita, jangan membuat keriuhan baru tentang hal-hal yang berteriak untuk perhatian saat diperlukan di tempat lain.

2 sen saya

Biasanya saya tidak membuat // TODO komentar tetapi menyimpannya dalam file yang terpisah. Masih tidak dapat menemukan / menulis perangkat lunak online untuk mengelolanya dengan mudah sehingga file TODO masih sangat berguna bagi saya karena ketika saya membuka proyek setelah waktu yang singkat saya lupa apa yang harus dilakukan sekarang dan kemudian saya melihat ke dalam file TODO dan melakukan pekerjaan . Saya mendapatkan "filename.cpp 354: Recode this bla bla bla" dan itu jauh lebih berguna daripada mencari // TODO komentar dalam file. Saya melakukan // TODO earler ketika saya malas tetapi saya hanya menghapus // TODO-lama dari file sumber dan tidak memperbaikinya ketika proyek bekerja dengan baik. Saya sangat menyarankan untuk memindahkan semua // TODO dari sumber ke tempat yang terpisah dan menyimpannya bersama dengan todos lain sehingga Anda dapat memprioritaskan tugas dengan mudah. Prioritas adalah hal yang sangat sulit TODO ketika Anda mendapatkan semua TODO Anda dalam berbagai file dan berbagai proyek.

Saya pikir ada yang hebat, tetapi tidak sendirian. Sebagai contoh:

//TODO: ADD MY CLICK EVENT LOGIC
throw new Exception();
//Even a simple messageBox could suffice

Pendekatan ini bekerja dengan sangat baik. Meskipun saya harus mengatakan bahwa menjadikan kebiasaan membuang pengecualian untuk mengingatkan Anda untuk menyelesaikan beberapa kode sebenarnya bukan pendekatan yang paling profesional. Tapi itu telah menyelamatkan saya dalam beberapa kasus di mana Anda berpikir Anda telah menyelesaikan sesuatu dan bahkan menuliskan Anda selesai ketika Anda belum.

Keuntungan besar dari komentar komentar atas jutaan lainnya atau lebih satu cara membuat daftar tugas adalah bahwa komentar todo bepergian dengan kode sehingga mereka tidak dapat dipisahkan.

Mungkin tempat yang lebih tepat untuk hal-hal seperti ini adalah pelacak masalah daripada kodenya.

Saya sangat menyarankan agar setiap TODO atau FIXME dimasukkan ke dalam log formal. Jika tidak, mereka mudah dicari, dan itu harus menjadi fase di setiap iterasi untuk memeriksa TODO dan FIXME yang beredar. Ini kemudian dapat di katalog, dan ditetapkan untuk pemulihan segera, atau tim dapat merencanakan untuk memperbaikinya pada waktu yang tepat.

Akhirnya, sekali diperbaiki mereka harus dihapus - jika mereka tidak dihilangkan secara sistematis setelah diselesaikan, mereka akan kehilangan efektivitasnya.

Intinya: Mereka lebih baik daripada tidak mencatat masalah sama sekali, tetapi Anda benar-benar harus mempertahankannya.

IntelliJ akan benar-benar mengingatkan Anda jika Anda mencoba melakukan kode yang memiliki TODO baru. Jadi, Anda selalu dapat menafsirkan TODO sebagai "ini benar-benar harus terjadi pada saat saya berkomitmen".

Ketika Anda menganggap "TODO" sebagai label semantik untuk komentar Anda, saya pikir itu masuk akal.

Dalam standar pengkodean perusahaan saya, kami menetapkan bahwa inisial pengembang yang bertanggung jawab harus disertakan dengan TODO ( yaitu , saya akan mengetik "SAA TODO:"). Saya pikir ini berguna, setidaknya sebagai konvensi, karena kalau tidak ada godaan untuk meninggalkan kode di bawah standar dengan catatan TODO untuk beberapa pengembang masa depan untuk berurusan dengan.

Bermanfaat, banyak IDE dapat dikonfigurasikan untuk menambahkan komentar ini ke daftar tugas, memungkinkan mereka diperlakukan sama untuk membangun wrnings dan tidak dilupakan tanpa batas waktu.

Metode yang lebih menjengkelkan, namun efektif mungkin untuk mengubah komentar agenda Anda menjadi pesan kompiler, sehingga Anda dan orang lain melihatnya ketika program dikompilasi.

dalam Delphi:

{$message 'todo: free this thing when you know its not going to blow up'}

Dalam pengalaman saya, TODOharus digunakan untuk menunjukkan bahwa sepotong kode tidak dapat digunakan dan memberi tahu pembaca apa yang diperlukan untuk membuatnya dapat digunakan (baik secara lokal atau di tempat lain).

TODOanotasi tidak boleh digunakan untuk menunjukkan bahwa beberapa bagian kode akan lebih baik jika dimodifikasi dengan cara tertentu. Contohnya termasuk kode kotor yang akan lebih dapat dikelola jika ditulis ulang atau fitur tambahan yang belum dibutuhkan siapa pun. Anotasi tersebut cenderung menumpuk dan menghasilkan grep TODOhasil yang tidak berguna.