Yeni başlayanlar için yorum yazmak mı?

Tomurcuk geliştiricilere yönelik kod yorumları yazmak için kesin bir rehber var mı?

İdeal olarak, yorumların ne zaman kullanılması (ve kullanılmaması gerektiği) ve hangi yorumların bulunması gerektiğini kapsayacaktır.

Bu cevap :

Ne yaptığınızı yorum yapmayın, ama neden yaptığınızı.

WHAT, onu desteklemek için uygun değişken adları seçerek temiz, okunabilir ve basit bir kodla halledilir. Yorumlar, kodun kendisinde gösterilemeyen (veya zor) kodlara daha yüksek düzeyde bir yapı gösterir.

yaklaşıyor, ancak deneyimsiz programcılar için biraz özlü (bence birkaç örnek ve köşe senaryosunda bir genişleme mükemmel olurdu).

Güncelleme : Buradaki cevaplara ek olarak, başka bir soruya verilen bu cevabın son derece alakalı olduğunu düşünüyorum .

Yorumların en büyük zayıflığının farkında olmalısınız: onlar bayatlanır. Diğer bir deyişle, kod değiştikçe, geliştiriciler kodla senkronize kalmak için yorumları nadiren günceller. Bu, onlara asla güvenemeyeceğiniz ve kod okumaya devam edemeyeceğiniz anlamına gelir. Bu nedenle, kodunuz kendi kendini belgeliyor olmalıdır. İşlevinizi ve değişken adlarını, kodun nesir gibi okuyacağı şekilde seçmelisiniz.

Bu yüzden kodun ne yaptığını belgelemeyin. Kendini belgeleyen kod buna dikkat etmelidir. Belge neden yapıyorsun. NEDEN genellikle işle ilgili kurallarla ya da mimarlıkla ilişkilidir ve sıklıkla değişmez ve WHAT'lerde hızlı bir şekilde bayatlamazlar. Belge kenarı davaları. Belge istisnaları. Belge tasarım kararları. Ve en önemlisi, düşündüğünüz tasarım kararlarını belgeleyin, ancak uygulamamaya karar verin (ve bunları neden kullanmaya karar verdiğinizi belgeleyin).

Robert C. Martin'in Temiz Kod kitabını okumalısın . Güzelce, yorumlara ihtiyacınız olursa, büyük olasılıkla doğru kodlamadığınızı açıklar. İdeal olarak, kodunuz "kendi kendini yorumlamalı" olmalıdır. Temiz Kodlayıcı kitabı bunun nasıl yapılacağını açıklar, böylece yorumlar gerekli değildir ve gerekli olduğu durumlarda yorumların nasıl yapılacağını iyi tarif eder. (Karmaşık bir matematik formülünü açıklamak gibi)

Code Complete, daha önce de belirtildiği gibi, yorum yazmak için çeşitli yönergelere sahiptir. Kısacası, bu PDL ve şöyle özetlenebilir:

1. Amacınızı açıklayın, kodun ne yaptığını değil. Bazı numaralar kullanmıyorsanız veya özel uygulamalar kullanıyorsanız uygulama ayrıntılarını tanımlamaktan kaçının. Örneğin, bölmek üzere değişen bitleri kullanmak, sınıf üyelerine erişmek için işaretçi aritmetik kullanmak veya bazı havuzlanmış nesneler için özel bir bellek ayırıcı kullanmak.

2. Önce sözde kodu (yani yorumları) yazın, sonra rutini / yönteminizi / işlevinizi tanımlamayı bitirdikten sonra gerçek kodu yazın. Kullanılan dil yüksek düzeyde olmasına rağmen özeldir, bu nedenle ayrıntılı olabilir.

3. Kodunuzu yazmadan önce kodunuzun ne yaptığını bile anlayın

4. Asıl koda yakın yorumlarınız olması

Amaç, modası geçmiş olabilecek uzun soluk, ilişkisiz yorumlardan kaçınmak, ancak kodun amacını ve amacını yansıtan yorumlardan kaçınmaktır. Üst düzey bir sözde kod kullanmak, uygulamayı yazmadan önce düşüncelerinizi netleştirmenize yardımcı olur.

Kitabı izlemek istememeniz durumunda GameDev.net'te [PDL'yi açıklayan] [1] bir bağlantı var.

Sadece basit ve ortak bir ilkeyi izliyorum: Yorumlarınız hangi kodun yapıldığını söylememeli, ama neden bunu yapıyor? Martin Fowler Makale ve Yeniden Faktoring ve Kod Kitabı Tamamlandı kitabında çok fazla bilgi var, ama ne yazık ki bu benim bilgilerime göre özetlenmiş bir biçimde değil.

Benim önerim, herhangi bir yorum yapmadan bazı kodlar yazmak ve ondan uzaklaşmak olacak. Bir yıl sonra tekrar gel ve oku. Kolayca anlamadığınız kısım, yorum yapmanız gereken kısımdır.

Evan Todd'un sadece faydalı yorum kategorileri hakkındaki görüşlerini özetlemesini gerçekten seviyorum ( blogundan alıntı yaparak ):

• Neyin yerine nedenini açıklayan yorumlar. Bunlar en faydalı olanıdır.
• Aşağıdaki dev kod grubunun ne yaptığını açıklayan birkaç kelimeyle yorumlar. Bunlar navigasyon ve okuma için kullanışlıdır.
• Veri yapısı bildiriminde, her alanın ne anlama geldiğini açıklayan yorumlar. Bunlar çoğu zaman gereksizdir, ancak bazen bir kavramı sezgisel olarak belleğe eşlemek mümkün değildir ve eşlemeyi tanımlamak için yorum yapmak gerekir.