C kodunu, üstbilgisini ve kaynak dosyalarını yorumlama

Question

C kodumu belgelemek için bir "en iyi uygulama" arıyorum. Herhangi bir projede olduğu gibi ".h" başlık dosyalarını ve ".c"

başlık dosyamda başlık dosyasında ne tür bir yorumunuz vardır? Ve kaynak dosyalarında? Soru şu şekilde ortaya çıkıyor çünkü başlık dosyamı iyi yorumladığımdan, c dosyaları bir karmaşaya benziyor.

Kodun iyi tutulmasıyla ilgili en iyi uygulamalarınız neler yorumlandı?

Answer 1

Başlığın kodu kullanıcıların içindir. Bu yüzden orada arayüzünü belgeleyeceğim: nasıl kullanılır, önkoşullar ve sonlandırmalar, vb.

.c dosyası sürdürücüler içindir. Orada, uygulamasını uygulamasının belgelemesini yapıyorum: şeylerin dahili olarak nasıl çalıştığı ve neden bu şekilde çalıştığı.

Answer 2

Eğer bu kişisel bir proje ise, orada benimseyebileceğin coding standards bol olduğunu önerebilirim (neredeyse hepsi yorumların nasıl düzenlendiğine dair bölümleri içerir).

Değilse, şirketinizin/teaam/projenizin zaten yerinde bir şey olduğunu düşünürdüm, bu yüzden kullanın.

Answer 3

Doxygen gibi bir araç tarafından uygulanan kuralları kabul etmenizi öneririm. Daha sonra sadece kod yorumları yerine, HTML/PDF/Latex vb. Belgeleri de oluşturabilirsiniz ve size iyi bir anlaşma sağlar.

cpp dosyaları Sana Dosya Üstbilgi ve Fonksiyon Başlığı için bir açıklama şablon oluşturmak önermek kaynak dosyaları için

Answer 4

hakkında Thomas ile katılıyorum.

Dosya Başlığı Açıklamaları durumunda, değişiklikleri kaydetmek için dosyanın, işlev adlarının, yazarın, oluşturma tarihinin ve geçmişinin kısa bir açıklamasını almalısınız.

İşlev üstbilgisi durumunda, işlevin ve çeşitli parametrelerin mantığını ve amacını açıklayabilirsiniz. Lütfen karmaşık bir mantık veya ortak davranıştan sapmanın yorumlarla belgelendiğinden emin olun.