Hata numaralarını kaynak dosyanın başında bir açıklamaya koymak iyi bir fikir mi? [kapalı]

Başlık numarasına dosyanın içine hata numaralarını koymak iyi bir uygulama mıdır?

Yorumlar şöyle bir şeye benzeyecek:

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

Yararlı görünüyor, ancak kötü uygulama olarak mı kabul ediliyor?

Bunu daha önce hem yazarlar tarafından hem de otomatik olarak dosyaya yazar, giriş yorumu ve tarih bilgisi eklemek için sürüm kontrol sistemleriyle entegre komut dosyaları ve tetikleyiciler tarafından yaptım.

Her iki yöntemin de iki ana sebepten dolayı oldukça korkunç olduğunu düşünüyorum. İlk olarak, özellikle bu yorumlar yaşlandıkça ve dosyanın mevcut durumu ile ilgisiz kaldığından dosyaya karışıklık ve gürültü katar. İkincisi, sürüm kontrol sisteminde halihazırda tutulanlardan gelen yinelenen bilgilerdir ve değişiklik setlerini destekleyen modern bir sürüm kontrol sistemi kullanıyorsanız, aslında değişiklikler hakkında bilgi kaybediyor.

Varsa, hata takip sisteminizle entegrasyonu düşünün. Bazı araçlar, bir check-in yorumundaki bir kusur veya görev kimliği numarasını izleme aracındaki bir öğeye bağlamanıza izin verir. Araçtaki tüm kusurlarınız, geliştirme istekleriniz ve çalışma görevleriniz varsa, bağlantıyı bu şekilde sağlayabilirsiniz. Tabii ki, bu proje için bu araçlara bağımlılığın olumsuzluğuyla birlikte geliyor.

Gelecekteki programcılar için bir uyarının bir parçası olarak, bunu yapabileceğim tek bir durum var: " foo()Burada doğrudan işlev çağrısı yapmayın ; bu, # 1234 numaralı hataya, yani ..." böcek izler.

Ve eğer kod foo()doğrudan çağrıya geçme eğiliminde olmayacak şekilde değişmişse , bu yorumu kaldırın. Sadece kodu tahriş eder ve patlatırdı.

Tamamen korkunç bir uygulamadır. Saf çoğaltma olan bir efekti elde etmek için çaba ekler; Başka bir deyişle, sadece taahhüt kütüklerini kullanarak eklediği tek şey tutarsızlık yaratma olasılığıdır. Kaynak dosyalarınız, hiç bakmadığınız sınırsız miktarda malzemeyle karışık hale gelir.

Tek fark edebileceğim tek şey, kaynak çıktısını sürüm kontrolüne erişmeden, örneğin bir çıktı okurken yapılandırabileceğinizdir. Ancak, çok az insan yazılım geliştirmenin karmaşıklıklarını izleyecek kadar yetkindir, aynı zamanda sürüm kontrolünü anlayamazlar.

Hayır.

İnsanların bir sürüm kontrol sistemi kullanmadan önce yaptıkları şey (yani kaynak kodun sadece zip dosyalarındaki yedekleri olduğu zaman).

Bu, IMHO, çok kötü bir fikir. 100 numaralı revizyondan sonra% 90 yorum ve% 10 kodunuz olacak. Bunu temiz ve okunaklı olarak düşünmezdim.

Gördüğüm tek nokta, kodunuzu SCC'ler arasında değiştirmeniz gerektiğinde ve ne nedenle olursa olsun, iki sistem arasında geçmişi aktaramazsınız (ancak geçmiş yorumlarını bu şekilde kaydettiğinizde bile, fark geçmişini kaybedeceksiniz. Ayrıca, yorumların kaydedilmesi yalnızca size biraz yardımcı olacaktır).

Herkesin bu fikre karşı olduğunu ve insanların neden yaptıklarının tarihi bir nedenini (kaynak öncesi kontrol dönemi) verdiğini görüyorum.

Ancak, şu anki şirketimde veritabanı geliştiricileri bu uygulamayı takip ediyorlar ve ayrıca hata kodunu kod parçası etrafında etiketliyorlar. Bazen kodda bir hata gördüğünüzde ve bu sorunu ortaya çıkaran hata düzeltmesini anında öğrendiğinizde yararlı olur. Veritabanı paketimde bu bilgilere sahip değilsek, bu uygulamanın kök nedenini bulmak kesinlikle kolay olmayacaktır.

Evet, kodu karıştırıyor, ancak bu kodun neden orada bulunduğunun nedenini bulmakta yardımcı oluyor.

Joel testindeki noktalardan biri

Böcek veritabanınız var mı?

Bu bilgiler, önemli olduklarını düşünüyorsanız, bir hata veritabanında tutulabilir, ancak yorumlarda sadece gürültü olur.

Burada iki sorunun olduğunu düşünüyorum. Birincisi, çoğu sistem revizyon yorumu girmenize izin verdiğinde neden tamamen farka güvenmelisiniz? İyi kod yorumları gibi, yalnızca değişimin kendisinin değil, değişimin neden yapıldığını keşfedersiniz.

İkincisi, bu yeteneğe sahipseniz, hepsini aynı yere koymak iyi bir pratik yapın. Artık ihtiyaç duyulmayan işaretli kod satırları için dosyayı incelemeye gerek yoktur. Çalışma kodunun içindeki yorumlar, neden bu şekilde kodlandığını anlatmak için var.

Bunu uygulamaya koyduğunuzda, oluşan alışkanlıklar, kod tabanının herkes için üzerinde çalışmasını kolaylaştırır.

Neden bu dosyayı değiştirdiğinizle birlikte ilişkili hata ve özellik takibi, size geçmişe bakmak için ne kadar derinlere ihtiyaç duyduğunuz ve muhtemelen farklara bakmanız gerektiği hakkında bir fikir verebilir. "Orijinal formüle geri dönme" isteğinde bulundum. Revizyon tarihinin neresine gideceğimi biliyordum ve sadece bir veya iki farklılığı gözden geçirdim.

Şahsen, dikkat çeken kod, deneme yanılma ile çözülen bir problem için devam eden bir çalışma gibi görünüyor. Bu karışıklığı üretim kodundan çıkarın. Kolayca içeri ve dışarı kod satırlarını kaydırmak, sadece kafa karıştırılmasını kolaylaştırır.

Taahhüt mesajlarına sahip bir VCS'niz ve yorum bırakmanız için bir seçenek sunan bir hata izleme sistemi yoksa, değişiklikleri takip etmek için en uygun olanı değil bir seçenek.
Bu bilgileri içeren bir elektronik tabloya sahip olmak veya bu "lüks" olmayan bir ortamdaysanız, kaynaklarınızın yakınında bir yerde oturan bir metin dosyası olması daha iyidir.
Ancak VCS ve hata takip sistemine yatırım yapmak için bir dava oluşturmaya başlamak için böyle bir ortamda olmanızı şiddetle tavsiye ederim :)

Bunu aklınızda tutun - kod genellikle onu destekleyen araçlardan daha uzun sürer. Farklı bir şekilde söylendiği gibi, sorun izci, sürüm kontrolü ve diğer tüm komut dosyaları geliştirme süreci boyunca gelişecektir. Bilgi kaybolur.

Kabul etmeme rağmen, dosya dağınıklığı can sıkıcı, bir dosyayı açmak ve araçlarını kullanmaktan vazgeçmeden geçmişini anlamak her zaman çok yardımcı oldu - özellikle de kodu koruyorsam.

Şahsen, hem araçlar hem de kod günlüğü için yer olduğunu düşünüyorum.

Biliyorum Git bu yapmaz ve basit cevabı "yeryüzünde neden olur oraya gitmek?"

Genel olarak daha az modüler bir tasarım. Bu çözüm altında, dosyalar artık içerik ve meta veriler arasında bir miktar karıĢmaktadır. Amazon S3 , dosyalara YAML ön maddesi ya da benzeri şeyler eklemeyen dosyaları depolamak için bir hizmet örneğidir .

Bir dosyanın herhangi bir tüketicisinin, önce sürüm kontrol sistemi aracılığıyla işlenmesi gerekir. Bu sıkı bir bağlantıdır, örneğin VCS'nizi desteklememesi durumunda favori IDE'niz bozulur.

Hayır, hata düzeltmelerinizi kodda yorum olarak izlemek iyi bir uygulama değildir. Bu sadece karışıklık yaratır.

Aynı zamanda bahsettiğiniz telif hakkı mesajı için de aynısını söyleyeceğim. Şirketinizin dışında hiç kimse bu kodu göremezse, telif hakkı iletisini eklemek için bir neden yoktur.

Sürüm izleme yazılımı kullanıyorsanız ( Git , SVN , vb.), Bu notları taahhüt mesajlarınıza eklemelisiniz. Hiç kimse sürüm notları oluşturmak veya hangi değişikliklerin yapıldığına ilişkin bir genel bakış görmek için her kod dosyasının başlığını incelemeyi istemez. Bu değişiklik günlüklerinin tümü sürüm izleme geçmişinizde, hata izleyicinizde veya her ikisinde birlikte depolanmalıdır.

Bu konuyla ilgili iyi bir okuma arıyorsanız, Temiz Kod'un dördüncü bölümünü öneriyorum .

Bu tartışmanın sıklıkla unutulan başka unsurları olduğunu düşünüyorum ancak bazı revizyon yorumlarının bir takıma uygun olduğu durumlar.

Paylaşılan kod temelli bir ekip ortamında çalışırken ve birkaç ekip üyesinin aynı kod alanlarında potansiyel olarak çalıştığı yerlerde, bir değişiklik yapıldığını belirten doğru kapsamda (yöntem veya sınıf) kısa bir gözden geçirme yorumu yapmak çok yararlı olabilir. birleştirme veya kontrol etme çakışmalarını hızla çözme.

Benzer şekilde, birkaç (özellik) dalın bulunduğu bir ortamda çalışırken, üçüncü bir kişinin (ana yapı oluşturucu) olası çatışmaları çözmek için ne yapılacağını belirlemesini kolaylaştırır.

IDE'den uzaklaşıp birisine neden bir şeyi değiştirdiklerini sormanız gerektiğinde, her iki takım üyesinin üretkenliği de rahatsız edicidir. Doğru kapsamdaki kısa not, bu kesintinin çoğunun azaltılmasına veya ortadan kaldırılmasına yardımcı olabilir.

Doğrudan bir kod parçasıyla ilişkilendirilen herhangi bir hata bilgisi, tüm değişimin bütünlüğü ardışık bir düzeltme ile değiştirildiğinde önemsiz hale gelir.

Koddan sürüm notları oluşturmak için harici araçlara (örneğin javadocs) güvenmek zorunda kaldığımızda fonksiyon özetine bilgi eklemek yaygındı. Modern versiyon kontrol araçları ile çoğunlukla işe yaramaz veya gereksizdir.

Gelecekteki geliştiricilerin değiştirmeye teşebbüs edeceği bazı belirsiz veya yıldız olmayan bir kodlamaya başvurmak zorunda kalırsa, sadece modüler bir kod parçasında bir yorum olarak anlaşılabilir. Kütüphane hatası / eksiklik.

Dosyanın başında kesinlikle böyle bir bilgi vermezdim - genellikle böyle bir şey bir bilet sistemine aittir.

Bununla birlikte, bilet sistemine ve / veya diğer belgelere yapılan atıfların anlamlı olduğu bazı durumlar vardır. Örneğin, tasarımın uzun bir açıklaması veya alternatiflerin açıklaması varsa. Veya bir şeylerin nasıl test edileceğine dair bilgiler veya bunun neden bu şekilde yapıldığına dair açıklamalar. Eğer kısa ise, dosyanın kendisine aittir; uzunsa ve / veya daha büyük bir fotoğrafla ilgiliyse, muhtemelen başka bir yere koymak ve referans vermek isteyeceksiniz.

Şu anda işyerinde görevlendirdiğim projede, her dosyanın başında bu tür hata numaraları listesi vardı; Bununla birlikte, halen projedeki geliştiricilerin hiçbiri artık buna katkıda bulunmuyor. Birçoğu, sürüm kontrol sistemimizi kullanarak bir dosyaya yapılan hataları takip etmekten daha düşük olduğu için gereksiz bir yer israfı olduğunu düşünüyor.

Pek çok düzeltme ve geliştirme geçiren kritik dosyalarda, bu listeler o kadar büyük hale geldi, koda ulaşmak için bunları kaydırmanız gerekiyor. Bu listeleri sıralarken kısa bir hata başlığı veya kısa bir açıklama olarak listelenen birkaç yanlış pozitif sonuçlanabilir.

Kısacası, bu listeler en iyisi işe yaramaz ve en kötüsü kodun aranmasını ve bulunmasını zorlaştıran devasa, kaotik bir alan kaybıdır.