Kod yorumlarında başlık yazıyor musunuz? [kapalı]

Yazdığım bazı eski kodlara göz atıyordum (üniversitede ilk yıl) ve kodun çeşitli bölümlerinden önce yorum başlıkları yazdığımı fark ettim. Gibi şeyler (bu bir Tekel oyunundan):

/*Board initialization*/
...code...

/*Player initialization*/
...code...

/*Game logic starts here*/
/*Displaying current situation*/
...code...

/*Executing move*/
...code...

/*Handle special event*/
...code...

/*Commit changes, switch to next player*/
...code...

Bu kod gerçekten süper açıksa gereksiz ve tartışmasız gereksiz olabilir, ancak dosyada tarandıkça, gerçek koda pek bakmama rağmen ne olduğunu ne kadar güçlü hissettim beni şaşırttı. Bunu kesinlikle belirli koşullara uygun olarak görebiliyorum, o yüzden merak ediyorum. Sizce bu iyi bir fikir mi? Yoksa çok mu?

Bu bir kod kokusudur. Bu ne diyor, neden değil .

Bu gerekliyse, kodu küçük işlevlere bölün.

Bunu her zaman yaparım. Her ikisi de kodun ne yaptığını işaretlemek ve muhtemelen daha da önemlisi, dediğin gibi, bir kod parçasını taramayı ve bulmayı kolaylaştırmak için. Bazen de, yorumlarda yer alan bir süreci yazacağım ve yorumların altındaki kodu 'giderim'.

Nedenini açıkça ifade etmeden kaç kişinin uygulamayı beğenmediğini ilginç buluyorum. Bunun gibi yorumların kaşlarını çatmasının nedeni, tek sorumluluk ilkesini ihlal ettiğinizin bir işareti olmasıdır.. Bu özel isim genellikle sadece OO bağlamında kullanılır, ancak genel konsepte uyum da denir ve diğer paradigmalar için de geçerlidir. Okullar, genellikle bir derece programının sonuna kadar bu tür tasarım ilkelerini öğretmezler. Aslında, bazı öğretmenler her şeyi tek bir dosyaya sıkıştırarak şeylerin daha kolay derecelendirilmesini sağlamak için ihlalini zorunlu kılar. Bu nedenle, birinci sınıf cehaletiniz mazur görülebilir ve "bir şey" yanlış olduğunu fark ettiğiniz ve yorumlarla açıklığa kavuşturmaya çalışmanız, koşullar altında bile övgüye değerdir, ancak genel olarak, yorumlarla kâğıt üzerinde çalışmak yerine belirsiz bir tasarımı düzeltmek daha iyidir.

Bu şeylere kodu daha açık veya açık hale getirmenin bir yolu olarak bakıyorum. Her tarafı nedir dosyasındaki yöntemlere dayalı ebilmek söylemek o zaman ancak eğer gerek yoktur var o zaman yararlı olabilir çoklu bölümleri için. Belki bir kod dosyası çok büyük olduğunda, bu tür yorumlara olan ihtiyacı azaltabilecek şekilde parçalanması gerekir.

Eğer bir takım içinde bir standart ile gelip böylece en azından aynı şekilde kodlama ve yorum böylece kod bakmak daha kolay olur yorum yapmak eğer söyleyebilirim.

Bunu yapıyorum çünkü sık sık kendime niyet veriyorum ya da "Veri temizleme burada başlıyor" gibi şeyler için uygun bir yer imi koyuyorum. Genellikle bu başlık altında ne yaptığım ve neden yaptığımın mantığı hakkında kısa bir bilgi vereceğim.

Artıklığı severim. Laboratuvar defterimi bir sebepten ötürü kaybedersem veya yıllar önce yazdığım kodu tekrar gözden geçirmem gerekirse, yaptığım şeyi ve neden yaptığımı bir araya getirmekten hoşlanmıyorum. Bu mantığın en azından bir kısmı kodda ise, en azından onunla tekrar çalışabilmem için yeterince belgelenmiştir.

Sanırım ona olan eğilimimin bir kısmı, programlamamın adil bir miktarıdır ve bu nedenle istatistiksel olarak tekrarlayıcıdır. Aramak için yararlı bir şekilde adlandırılmış bir işleve sahip olduğum birkaç parça kod olsa da, genel bir doğrusal model işlevi gibi bir şeyin birkaç düzine oldukça benzer kullanımına sahip olabilirim. Bunlardan hangisinin "Seçim A veya Seçim B veya C'ye karşı sonuçlar ne kadar hassas olduğunu" ve hangisinin başka bir şey olduğunu bulmak yararlıdır. Bu genellikle başlıklarla hızlandırılır.

Bunun, düzinelerce işlevi olan devasa kaynak dosyalarınız olduğu ve bunları böyle parçalar halinde gevşek bir şekilde düzenleyebileceğiniz durumlarda yararlı olduğunu düşünüyorum. Ancak bunu daha küçük, daha odaklanmış kaynak dosyalardan daha iyi sevdiğimi söylemiyorum ...