TODO yorumları mantıklı geliyor mu? [kapalı]

Oldukça büyük bir proje üzerinde çalışıyorum ve bunun için bazı çeviriler yapmakla görev aldım. Tercüme edilmemiş tonlarca etiket vardı ve ben kodu araştırırken bu küçük kodu buldum

//TODO translations

Bu bana kendinize (ve başkalarına) bu yorumların anlamını düşündürdü, çünkü çoğu geliştiricinin belirli bir kod parçasını aldıktan sonra yaptıklarını hissediyordum ve bunu yapana kadar asla bakmaları gereken şeyi yapıyor. korumak veya yeni işlevler eklemek için. Böylece bu TODOuzun süre kaybolacak.

Bu yorumları yazmak mantıklı mı yoksa bir beyaz tahtaya / kağıda / geliştiricilerin odağında kaldıkları başka bir yere yazılmalı mı?

Ben kullanma eğiliminde // todoşeyler için bir yorum var gerçekleşmesi, ancak ben hemen yapamaz.

Ben onları aramak (Visual Studio sizin için böyle bir yorum listeler güzel özelliği vardır) ve işler sağlamak - Ben de onlara kadar kovalamak emin edilir yapılır.

Ancak, dediğiniz gibi, herkes onlar hakkında titiz değil ve birçok yorum gibi, zamanla çürümeye meyillidir.

Bunun daha çok kişisel bir tercih olduğunu söyleyebilirim - yapılması gerekenleri belgelemek ve takip etmek için // todo, içeride olup olmadığının, notların veya beyaz tahtanın (nerede olamayacağı gibi) olması önemli değil eylemde bulunmak.

Modern IDE'ler TODOyorumları tanıyorlar ve kendi panellerinde / pencerelerinde / sekmelerinde görülebiliyorlar, bu yüzden teorik olarak kaybolmuyorlar (Eclipse ve Visual Studio'yu düşünüyorum, ikisini de tanıdıklarını hatırlayacak kadar biliyorum).

Hatta gibi ek açıklama kelimeleri yapılandırabilir FIXME, BEWAREya başka bir şey özelleştirmek istediğiniz. Ancak, projenizdeki diğer geliştiricilerin IDE'lerini de aynı şekilde özelleştirmeleri gerekecektir.

Şimdi, "teorik olarak" yazdım çünkü kaybolmamasına rağmen, TODO çoğu zaman uygulamanın "şu anda" düzgün çalışması için gerekli olmayan bir şeyle ilgilidir. Ve "şu anda", projenin türüne / boyutuna bağlı olarak 5 dakika ile 5 yıl arasında uzayabilir :-)

Son olarak, benim görüşüme göre, kodda, doğru yerde, "değişikliği nerede yapmalıyım" sorusunu tam olarak kodun dışındaki bir yere sormaktan daha mantıklı geliyor.

Düzenleme: Wikipedia’nın TODO’nun tarihi ve sahibi de dahil olmak üzere yorumlarda yazdığı gibi iyi bir uygulama olduğu kabul edilir.

Biraz mantıklı gelebilir, en azından bazen onları kullanıyorum. Anahtar nokta, basit metin arama ile kolayca bulunabilmeleri için TODOveya gibi tutarlı etiketler kullanmaktır FIXME.

Örneğin, "hızlı ve kirli" çözümler aşağıdaki gibi bir etiketi etiketlemek için uygundur:

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

Kod yapılması gerekenleri yaparsa ve kimse şikayet etmezse, yorum zarar vermez. Kodu güzelleştirmek için zamanınız varsa, FIXMEetiketleri aramaya başlamak kolaydır .

Sektörümde, geliştiricilerin yorum yapmak yerine JIRA (veya benzeri) girişleri yapmaları teşvik ediliyor çünkü herkes // todogirişleri görme şansına sahip değil . Ancak bazen büyük projelerde, satırlar boyunca özel bir öznitelik tanımlanır:

[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;
    }
}

Ve sonra bir yöntem bu şekilde dekore edilebilir ...

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

Ve yüksek yükselmeler ortaya çıkıp bunları otomatik olarak toplayabilir. Basit bir // todohatırlatma için gereğinden fazla olabilir , ancak etkilidir. Ayrıca bir .NET platformu gerektirir.

TODO sadece bir yorum alt formu. Yorumlar, yazarın neyi ileteceğini ve onu nasıl ileteceğini bilmek konusunda uzmansa, çok faydalıdır. Burada mizah anlayışı, yıllar sonra koruyucuları memnun etmek için küçük dozlarda da uygulanabilir.

Geçen yıl kodumun bir kısmının emekli olduğuna dair bir telefon aldım. 16 yıl boyunca üretimde kaldığından ve bakımdan sağ kaldığından oldukça etkilendim. Bu yüzden, kodunuzun UZUN bir süre dayanabileceğini unutmayın. Niyet, gelecekteki ihtiyaçlar ve benzerleriyle ilgili yorumlar, ilk defa kodunuza bakan, bundan yıllar sonra birisine yardım etmede uzun bir yol kat edebilir.

Tecrübelerime göre değişir. Asıl faktör, ekibin bu "küçük" yorumları takip edecek kadar disiplinli olup olmadığıdır. Eğer yaparlarsa evet, anlamlıdırlar. Olmazlarsa, bu yorumlar sadece zaman kaybıdır ve başka seçeneklere, örneğin hikaye kartlarına bakmak isteyebilirsiniz.

Şahsen ara sıra TODO yorumları kullanıyorum ancak bunlar genelde kısa sürüyorlar ve genellikle bir, iki veya üç gibi çok az sayıda bunlara sahibim. Onları kod tabanında bir işaretçi olarak her şeyden çok kullanırım. Onlarla ilgilenmek için çok beklersem, ne yapmam gerektiğini düşündüğümü unuturum.

Tercihim her zaman bunları kullanmamak ve bunun yerine uygun hikaye kartlarını veya biriktiricileri veya benzerlerini kullanmak olacaktır. Bir görev için bir mekanizma kullanın.

Onları geçmişte yazardım, ama genelde onları takip etmediğini öğrendim.

Bu yüzden şimdi onları sadece meşgul olduğum işi bitirdikten hemen sonra üzerinde çalışmak istediklerimi işaretlemek için kullanıyorum. Örneğin, yeni bir işlev uygularım ve kullandığım bir işlevin küçük bir hata olduğunu fark ediyorum; Mevcut görevimde raydan çıkmamak için bunu düzeltmek için bir FIXME yapıyorum.

Bana yardım etmek için, kodunda FIXME varsa CI kurulumlarımız başarısız olacak şekilde ayarlanmıştır.

Hemen çözülemeyen olası sorunları fark ederseniz, onlar için bir bilet / hata / sorun açın. Bu şekilde, tüm böcekler gibi önceliklendirilebilirler. Bunun DB veritabanındaki bazı sorunlardan ve TODO kodundaki bazı kodlardan daha iyi olduğunu düşünüyorum.

İsteğe bağlı olarak, daha sonra :-) hata kimliğiyle bir TODO'ya koyabilirsiniz.

Bence TODOyorumlar bir anlamda mantıklı. Özellikle yinelemeli çalışıyorsanız (çevik ve TDD mağazalarında sıkça olduğu gibi), tanıyacağınız şeyler çok uzun zaman önce ihtiyaç duyulacak, ancak tam o anda ve orada uygulamak için dolambaç yapmak istemediğiniz şeyler olacaktır.

Çirkin olan şey, bu tür yorumların kod tabanında kalmasıdır. Aktif olarak bir özellik üzerinde çalışırken, onları içeride bırakmak iyidir, ancak özelliği tamamlamaya yaklaştıkça onlardan kurtulmaya odaklanmalısınız. Onları gerçekten uygun, çalışma koduyla değiştirmeyi denemek istemiyorsanız, en azından ilgili işlevselliği hesaba katın. JoonasPulakka'nın örneğini ödünç almak için, ilk önce kodun yazdığı yer

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

bunu gibi bir şeye değiştirebilirsin

ConnManager.getConnection(GetDatabaseName());

Şimdilik, GetDatabaseName (), başladığınız dizenin aynısını döndüren bir saplamadır. Bu şekilde, gelecekteki genişlemenin açık bir noktası vardır ve orada yapılan değişikliklerin veritabanı adının gerekli olduğu her yere yansıtılacağını biliyorsunuz. Veri tabanı adı orta derecede jenerik ise, bu sürdürülebilirlikte büyük bir gelişme olabilir.

Kişisel olarak, TODOniyetim aynı olsa da , kesinlikle kendi yerine bir anahtar kelime kullanıyorum : Bildiğim şeyleri tekrar gözden geçirmek gerekecek şekilde işaretlemek. Ayrıca, kodumu kontrol etmeden önce, normalde kodda hiçbir yerde görünmemesi için seçilen anahtar kelimeyi genel bir kaynak kodu araması yapıyorum. Eğer bulunursa, bir şey unuttuğumu biliyorum ve devam edip düzeltebilirim.

Programcı adını / imzasını yoruma eklemeye gelince , bir kaynak kod sürüm kontrol sisteminiz varsa bunu yapmanın aşırı doğru olduğunu düşünüyorum ( doğru mu?). Bu durumda, suçlama özelliği, yorumu kimin eklediğini veya yoruma dokunan bir değişikliği en son kontrol eden kişiyi daha doğru bir şekilde size söyleyecektir. Örneğin, Visual Studio'da bu, kaynak kontrol özellikleri arasında bulunan "Not" özelliğini kullanarak kolayca gerçekleştirilir.

Belirsiz bir gelecekte o koda geldiklerinde başkasının düzelteceği fikrine sahip bir TODO veya FIXME yazarsanız, rahatsız etmeyin derim. Kodu atlar ve IDE'nizin bu bilgiyi toplayan raporlama bölümünü karıştırırlar.

Yararlı olması için, kodunuzu (çok) yakın bir gelecek için imlemek için bir araç sağlamalıdır, böylece uygun durumda daha hızlı geri dönebilirsiniz. Başka bir deyişle, onları en kısa sürede kaldırmak için kodunuza yerleştirirsiniz.

Daha uzun ömürlü olan herhangi bir şey aslında ait olduğu üssünüzün içine yerleştirilmelidir.

Hayatımızda yeterince gürültü var, başka bir yerde ihtiyaç duyulurken dikkat edilmesi gereken yeni bir şeyler oluşturmayalım.

Benim 2 kuruş

Genelde // TODO yorumu yapmam ama hepsini ayrı dosyada tutuyorum. Hala kolay yönetmek için çevrimiçi yazılım bulamıyor / yazamıyorum, bu yüzden TODO dosyaları benim için hala en yararlı olanı çünkü projeyi kısa bir süre sonra bile açtığımda şimdi ne yapacağımı unutuyorum ve sonra TODO dosyasına bakıp işi yapıyorum . "Dosyaadı.cpp 354: Bu bla bla bla'ı yeniden kodladım" ve dosyada // TODO yorumunu arattıktan sonra çok daha kullanışlı. Tembelken // TODO earler yaptım ama bu eski // TODO'ları kaynak dosyadan kaldırdım ve proje iyi çalıştığında bunları düzeltmem. Tüm // TODO'ları sosisten ayrılmadan ayrı bir yere taşımanızı ve diğer todoslarla bir arada tutmanızı şiddetle tavsiye ediyorum, böylece işleri kolaylaştırabilirsiniz. Tüm TODO'larınızı çeşitli dosyalarda ve çeşitli projelerde bulduğunuzda öncelik, çok zor bir şeydir.

Bence orada harika ama yalnız değil. Örneğin:

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

Bu yaklaşım oldukça iyi çalışıyor. Yine de, bazı kodları tamamlamanızı hatırlatmak için istisnalar atma alışkanlığı haline getirmenin bir zorunluluk olmadığını söylemek zorundayım. Ama bir şeyleri tamamladığını sandığın bazı durumlarda beni kurtardı, ve yapmadığın zaman bile seni yazdı.

Diğer milyonlarca kişiden herhangi birinin görev listesi oluşturabilmesi için yorum yapmasının en büyük avantajı, yorum yapmanın kodlarla birlikte seyahat etmesini sağlamaktır.

Muhtemelen böyle şeyler için daha uygun bir yer, koddan ziyade sorun izcidir.

Her TODO veya FIXME’nin resmi bir kütüğe girilmesini şiddetle tavsiye ederim. Olmazlarsa, kolayca aranabilirler ve seçkin TODO'ları ve FIXME'leri kontrol etmek için her yinelemede bir aşama olmalıdır. Bunlar daha sonra kataloglanabilir ve derhal telafi edilmek üzere ayarlanabilir ya da ekip bunları uygun zamanda düzeltmeyi planlayabilir.

Son olarak, bir kez düzeltildiklerinde kaldırılmaları gerekir - eğer çözüldükten sonra sistematik bir şekilde ortadan kaldırılmazlarsa, etkinliklerini kaybedeceklerdir.

Alt satır: Sorunları günlüğe kaydetmemek yerine daha iyidirler, ancak aslında onları korumanız gerekir.

Yeni TODO'lar içeren bir kod girmeye çalışırsanız, IntelliJ sizi gerçekten uyaracaktır. Bu nedenle, bir TODO'yu her zaman "iş yaptığım zaman bu gerçekten olması gerektiği" olarak yorumlayabilirsiniz.

"TODO" yu yorumunuz için anlamsal bir etiket olarak gördüğünüzde anlamlı olduklarını düşünüyorum.

Şirketimin kodlama standartlarında, sorumlu geliştiricinin adının baş harflerinin TODO'ya dahil edilmesi gerektiğini belirtiyoruz ( yani , "SAA TODO:" yazardım). Bunun en azından bir konvansiyon olarak faydalı olduğunu düşünüyorum, çünkü aksi halde gelecekteki bazı geliştiricilerin uğraşması için TODO notuyla standart altı kod bırakma isteği vardır.

Yararlı bir şekilde, birçok IDE bu yorumları bir görev listesine eklemek üzere yapılandırılabilir ve böylece yazım oluşturmada benzer şekilde muamele edilmelerine izin verilir ve süresiz olarak unutulmaz.

Daha iğrenç, ancak etkili bir yöntem muhtemelen yapılacaklar yorumunuzu derleyici mesajlarına dönüştürmektir, bu şekilde siz ve diğer herkes program derlenirken onu görür.

Delphi'de:

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

Tecrübelerime göre, TODObir kod parçasının kullanılamaz olduğunu belirtmek için kullanılmalı ve okuyucuya kullanılabilir kılmak için neyin gerekli olduğunu (yerel olarak veya başka bir yerde) söyleyecektir.

TODOek açıklamalar, bir şekilde değiştirilirse bir parça kodun daha iyi olacağını belirtmek için kullanılmamalıdır. Örnekler, yeniden yazılmışsa daha fazla bakım gerektirebilecek kirli kodları veya henüz kimsenin ihtiyaç duymadığı ekstra bir özelliği içerir. Bu ek açıklamalar yığılma eğilimi gösterir ve grep TODOişe yaramaz sonuçlar verir.