JQuery kodunun yorumlarından birçok sayı gördüm . (Aslında, jQuery kodunda 69 sayı vardı.) Bence iyi bir uygulama olurdu, ama hiç bir kılavuz görmedim.
İyi bir uygulama ise, bu uygulama için yönergeler nelerdir?
JQuery kodunun yorumlarından birçok sayı gördüm . (Aslında, jQuery kodunda 69 sayı vardı.) Bence iyi bir uygulama olurdu, ama hiç bir kılavuz görmedim.
İyi bir uygulama ise, bu uygulama için yönergeler nelerdir?
Yanıtlar:
Genel olarak, iyi bir uygulama olarak düşünmem. Ancak istisnai durumlarda, kod karmaşık bir sorunu düzeltmek için sezgisel olmayan bir şey yapmak zorunda olduğunda çok faydalı olabilir ve herhangi bir açıklama yapılmadan birisinin bu garip kodu "düzeltmek" ve böylece onu kırmak isteyebileceği riski vardır. , akıl yürütmeyi açıklamak sorundan bilgileri çoğaltan büyük bir yorum ile sonuçlanacaktır.
Kaynak denetim sisteminize ilgili düzeltmeyi gerçekleştirdiğinizde sorun numarasını taahhüt mesajına eklemenin yeterli olduğunu düşünüyorum.
Örneğin:
Hata # 203: Veritabanı bağlantıları artık 30 saniye sonra zaman aşımına uğramıyor.
Kodda değişiklik sayıları, geliştirici isimleri veya tarihler eklemenin sadece kod tabanını kirlettiğini ve gerçekten kaynak kontrol sisteminiz tarafından harici olarak yönetilmesi gerektiğini buluyorum.
Buradaki diğer posterlere tamamen katılmıyorum!
İzleme referanslarıyla kod açıklamaları, bakım programlaması için çok yardımcı olabilir.
Bir hatayı takip edersem ve kodun alanına yaklaşırsam, son zamanlarda değiştirildiğini ve değişimin bağlamına bir bağlantı olduğunu görmek için bir tanrı gönderimi olur.
Evet, kaynak kodu kontrolümüz var, ancak dosyaları ve modülleri tek tek kontrol etmek oldukça yavaş olabilir. Sen istemek bunlar son değişiklikler için üzerinize atlamak için.
Kod tabanında gerçekten eski olanları gördüğümde muhtemelen onları kullanımdan kaldırırdım, ancak daha yeni olanları tutmak için çok az aşağı tarafı ve akıllıca kullanırsanız potansiyel olarak geliştirici zamanını bir sürü saklayın.
Aslında hata izleme sisteminize yapılan bu küçük referansların koddaki ayrıntılı yorumlara tercih edildiğini düşünüyorum.
git gui blame <filename>kod geçmişine göz atmak için çok hızlı bir GUI sağlar. Kod yorumlarını geçmişle birleştirmek için bir araç kullanmak, kod için herhangi bir satır içi yorumdan çok daha iyi dokümantasyon sağlar. Diğer bir deyişle, iyi taahhüt mesajları yazmaktan rahatsız olursanız (iyi bir taahhüt mesajı kabaca neden bu yamanın uygulanması gerektiğini açıklayan bir e-posta mesajına eşit olmalıdır).
"Temiz Kod" politikasına abone olursanız, muhtemelen yorum eklemenin iyi bir uygulama olup olmadığını kendinize sormanız gerekir. Kod yalnızca bir açıklama ile netleştirilebiliyorsa, bir tane ekleyin, aksi takdirde kodunuzu basitçe okuyarak ne yaptığını kolayca anlayabilmeniz gerekir (değişkenleriniz, yöntemleriniz, vb. İçin mantıklı isimler kullanıyorsanız).
Yorumlamanın iyi bir uygulama olup olmadığı konusunda kişisel görüşünüz ne olursa olsun, bir yorum, yorumun başvurduğu koda doğrudan değere sahip bilgiler içermelidir. Bu durumda soru, sorun numarası eklemenin koda değer verip vermeyeceğidir. Sorun numarasını ekleyerek gördüğüm sorun, birkaç sorunu karşılamak için ağır bir şekilde değiştirilebilecek bir kod bölümüne sahip olabilmeniz ve bir süre sonra, belirli bir sorunla ilgili hangi değişikliklerin doğru bir şekilde tanımlanmasının imkansız olabileceğidir. Müteakip konular örneğin, önceki konularla ilgili kodun yeniden düzenlenmesini gerektirebilir. Bu belki de aşırı bir örnektir, ancak koddaki yorumlardaki sayıların nasıl işe yaramaz hale gelebileceğini göstermektedir.
Az önce açıkladığım durumun asla olmayacağını garanti edebilseydiniz, konunun ne hakkında bir açıklama olmadan sorun numarasının kendisinin hala oldukça yararsız olduğunu iddia edebilirim ve yine de, tüm bu bilgiler gerçekten sizin sorun izleme sistemi ve çoğaltılması gerekir. Sorun numarasını not etmek için daha iyi bir yer, bir yorum olarak sürüm kontrol sisteminizde olacaktır. Avantajı, sürümleri karşılaştırabilmeniz ve belirli bir sorunla ilgili kod değişikliklerini görebilmenizdir, ancak sorun numarasının kendisi, koddaki değişikliğin nedenini incelemek istiyorsanız gerekli tanımlayıcıyı sağlar.
Tüm bunları göz önünde bulundurarak, kodunuzdaki yorumlara sayı ekleme gibi gerçekten iyi bir uygulama olmadığını öneririm.
Yorumun kendisinde kısa bir açıklama yaparken, daha fazla okumak için bir konuya atıfta bulunmanın iyi bir uygulama olduğunu düşünüyorum.
Ben genellikle sadece bu kod parçası ince veya sezgisel olmayan bir şey varsa yorum eklemek. Bazı ince sorunlar birkaç satırda tamamen açıklanamadığından ve düzinelerce yorum satırı eklemek istemediğimden, bunun neyi başarmaya çalıştığını açıklayan kısa bir yorum ekleyeceğim ve detaylar.
Örneğin:
// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details
123 nolu konu bu saldırının nasıl görünebileceğini ve yeni kodun saldırıya karşı neden bağışık olduğunu açıklamaktadır.
Veya:
// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.
Sorun sayılarını kaynağınıza koymanın temel sorunu, artık harici bir referansınız olmasıdır. Bu yüzden sorunu kaybetmeyeceğinizden emin olmalısınız.
Kaynak kodunuz sürekli entegrasyona bağlandığında, sorun mesajının taahhüt mesajlarına dahil edilmesi çok yararlı olabilir. TeamCity gibi uygulamalar bu bilgileri çıkarır ve daha iyi raporlamaya olanak tanır.
Yukarıda söyledi ile% 100 emin değilim kod yorumlarından çeker. Sorun sayıları devam ederse (örneğin sorun izleyicileri değiştirmezseniz) ve belirli bir proje için çok fazla sorununuz yoksa koda sayıların dahil edilmesi iyi sonuç verir.
Sorunu ve çözümü açıklarsanız daha yararlı olabilir, böylece bir sonraki geliştiricinin sorun numarasını araması gerekmez. Derleyici veya küçültücü, kod wild'a bırakılmadan önce yorumlarınızı kaldıracaktır, böylece sonuç üzerinde herhangi bir etki olmamalıdır.