Apakah komentar TODO masuk akal? [Tutup]


86

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?


2
(beberapa) IDE melacaknya. Saya menggunakannya secara bebas ketika saya belum sepenuhnya menyempurnakan implementasi modul tetapi kontrak memuaskan bagi saya (atau orang lain) untuk melanjutkan pengembangan pada bagian terkait lainnya.
smp7d

3
TODO bagi saya lebih seperti "harus dilakukan untuk mengoptimalkan, tetapi tidak perlu mengirim"
Jake Berger

8
Setiap kali saya memikirkan tugas yang harus dilakukan atau kasus tepi yang perlu diperiksa untuk fitur yang sedang saya kerjakan, saya menghentikan apa yang saya tulis (bahkan pernyataan tengah) dan menambahkan TODO untuk itu (bahkan jika hanya garis di atas) . Ini membantu mencegah bug "Oh yeah, aku bahkan memikirkan itu" . Sebelum saya melakukan fitur, saya memeriksa TODO. Mereka tidak pernah berkomitmen, tetapi sejak saya mulai melakukan ini, jumlah bug saya turun secara drastis .
BlueRaja - Danny Pflughoeft

8
Saya selalu menggunakan #warning TODO: …jika saya tidak ingin melupakan TODO.
sayap kanan

2
@WTP: Visual Studio, R #, Netbeans, Eclipse dll. Semua termasuk alat untuk melihat semua TODO dalam solusi / ruang kerja. Tidak perlu hack lama itu lagi.
BlueRaja - Danny Pflughoeft

Jawaban:


107

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).


18
Eclipse menyoroti mereka dan mengkonsolidasikan daftar mereka untuk Anda juga. Dan menulis komentar TODO ketika pikiran itu ada di pikiran Anda bukanlah ide yang buruk, bahkan jika Anda tidak pernah benar-benar melakukannya. Seseorang yang murah hati mungkin sebenarnya sedang menelusuri kode untuk mencari hal-hal yang harus dilakukan (OSS).
Hobs

4
Resharper memiliki daftar TODO yang bagus juga, ini berfungsi lebih baik daripada yang standar VS (terlihat di lebih banyak file).
CaffGeek

Yap, diberikan daftar di IDE Anda, mereka sangat membantu. Saya akan mengatakan mereka sangat terbatas digunakan, karena basis kode mungkin sangat besar.
Insinyur

4
Karena komentar membusuk, saya selalu berkencan dan mengawali komentar saya. Jika komentar berusia tiga tahun dari empat kontraktor yang lalu, Anda mungkin dapat menghapusnya.
user1936

2
Karena penyelamat dan tanggal disebutkan, saya menggunakan Templat Langsung Resharper sederhana "// TODO $ user $ ($ date $) -"
dark fader

56

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.


32
Saya pikir tanggal dan pemilik TODO hanyalah kebisingan. Untuk itulah kontrol versi (dan fitur menyalahkan) (jika Anda benar-benar membutuhkan informasi).
sleske

3
Saya tidak berpikir wikipedia yang mengatakan "Itu disarankan" adalah citable; waspada bau. Tautan yang lebih baik ke artikel yang mengklaim ini.
phresnel

@phornel juga ada kutipan terkait dengan "saran" ini, jadi saya tidak merasa perlu mengulangi ini di sini, kalau tidak saya setuju dengan fakta bahwa mengutip fakta wikipedia yang tidak didukung oleh apa pun bisa berbahaya
Jalayn

@sleske Saya akan cenderung setuju tentang menjaga kebisingan minimal TETAPI Saya pikir IDE tidak secara otomatis memberi Anda informasi dari repositori (kecuali saya salah, Anda harus membandingkan versi secara manual) jika Anda tidak secara eksplisit menulisnya .
Jalayn

1
Fitur "annotate" Visual Studio memudahkan untuk melihat siapa yang terakhir memeriksa perubahan pada berbagai bagian file yang sedang Anda kerjakan, dan dengan perubahan mana. Tidak sempurna, tetapi dalam banyak kasus (terutama dengan TODOkomentar) cukup dekat untuk bermanfaat.
CVn

13

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.


3
"FIXME" dan "TODO" memiliki arti berbeda bagi saya. Terjemahan, nilai hard-coded, atau menangkap pengecualian dengan ex.printStacktrace()adalah TODO bagi saya. Di sisi lain, FIXME akan berurusan dengan Pengecualian yang terjadi kadang-kadang, kebocoran memori, atau jenis bug lain yang Anda temukan tetapi tidak sepenuhnya dianalisis / diperbaiki.
rds

10

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.


5
Komentar TODO di-lcoalized ke kode baris. Menurut saya, tiket lebih global dan lebih tinggi. Dan saya kira penjelasan ini adalah pembunuhan yang berlebihan. TODO memiliki lebih banyak kesempatan untuk bekerja pada lebih banyak editor.
rds

6
Industri Anda ? Yang mana itu? Saya tidak tahu seluruh industri yang mendorong penggunaan JIRA ?!
phresnel

7

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.


1
Jika sudah ada di sana selama lebih dari satu dekade, itu tidak benar-benar diperlukan dan dengan demikian menambahkan TODOkomentar tidak masuk akal.
CVn

2
Itu mengasumsikan mereka tidak pernah berubah. Seperti halnya kode, komentar dapat berubah dengan penambahan, penghapusan, dan modifikasi. Daftar TODO lebih cenderung diubah dengan cara ini. Saya yakin bahwa dalam dekade terakhir sejak saya terakhir menyentuh kode itu komentarnya diubah.
Pete Mancini

6

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.


6

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 :-).


3

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.


3

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


2

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.


7
Dan kemudian Anda memasukkan fungsi baru di filename.cpp, katakanlah di sekitar baris 200 dalam kasus contoh Anda, karena Anda merasa perlu untuk memperbaiki beberapa bagian kode. Tiba-tiba referensi Anda tidak ada artinya. Saya lebih suka IDE yang menunjukkan mereka kepada saya di mana mereka berada sekarang , bukan di mana mereka berada ketika saya melihat kebutuhan TODOapa pun.
CVn

Ya Anda benar) kadang-kadang sulit bagi saya untuk menemukan garis tetapi saya menghadapinya. Dan ya. Saya dapat menggunakan keduanya untuk menemukan file atau IDE dengan mudah tetapi untuk mengetahui apa yang harus dilakukan di tempat yang terpisah.
cnd

2

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.


2
Dalam hal ini Anda bisa melempar new NotImplementedException()yang menyiratkan ToDo.
CodesInChaos

Dalam CI suka menggunakan assert(0 && "TODO[cmaster]: Add click event logic");. Sederhana dan sangat efektif dalam menyampaikan pesan kepada saya seandainya saya melupakan TODO ...
cmaster

1

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.


0

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.


-1

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".


-1

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.


-2

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'}

-4

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.


Apakah ini hanya pendapat Anda atau Anda dapat mendukungnya?
agas

Ini pendapat dan saran saya berdasarkan pengalaman saya. Beberapa orang menggunakan komentar TODO untuk mengatakan "Saya tahu cara menulis kode yang baik tetapi saya tidak akan melakukannya karena saya tidak peduli, tapi hei saya menulis TODO di sini sehingga benar-benar menunjukkan bahwa saya tahu cara menulis kode bersih".
Martin Jambon
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.