Diyelim ki nispeten büyük bir proje geliştiriyorum. Tüm sınıflarımı ve işlevlerimi Doxygen ile zaten belgeledim, ancak her kaynak kod dosyasına bir "programcı notu" koymak için bir fikrim vardı.
Bunun arkasındaki fikir, meslekten olmayan bir terimle belirli bir sınıfın nasıl çalıştığını açıklamaktır (sadece çoğu yorumda neden olduğu gibi değil ). Başka bir deyişle, diğer programcılara bir sınıfın nasıl çalıştığı hakkında başka bir görüş vermek.
Örneğin:
/*
* PROGRAMMER'S NOTES:
*
* As stated in the documentation, the GamepadManager class
* reads joystick joystick input using SDL and 'parses' SDL events to
* Qt signals.
*
* Most of the code here is about goofing around the joystick mappings.
* We want to avoid having different joystick behaviours between
* operating systems to have a more integrated user experience, since
* we don't want team members to have a bad surprise while
* driving their robots with different laptops.
*
* Unfortunately, we cannot use SDL's GamepadAPI because the robots
* are interested in getting the button/axes numbers, not the "A" or
* "X" button.
*
* To get around this issue, we created a INI file for the most common
* controllers that maps each joystick button/axis to the "standard"
* buttons and axes used by most teams.
*
* We choose to use INI files because we can safely use QSettings
* to read its values and we don't have to worry about having to use
* third-party tools to read other formats.
*/
Bu, yeni programcıların / katılımcıların nasıl çalıştığını anlamalarında büyük bir projeyi kolaylaştırmak için iyi bir yol olabilir mi? Tutarlı bir kodlama stili ve 'standart' rehber organizasyonu sürdürmenin yanı sıra, bu durumlar için herhangi bir 'standart' veya önerileri var mı?
32
Cehennem hayır. Kodunuz okunamıyorsa, belgeler yardımcı olmaz.
—
Telastyn
@jeffo - sorun şu ki, bunun için zaman ayırmanın bir kez olabileceği yönünde. Kodu okunaklı tutma süresi zamanla olur. Proje gençken veya Mükemmeliyetçi Joe hala takımdayken yapılan bu tür belgelerle bulundum. Daha sonra terk edildi ve yorumlar devam etti, artık doğru değil.
—
Telastyn
En azından daha yüksek bir seviyede, bir projenin ne yaptığını, nasıl çalıştığını ve mimaride hangi tradeolyonların yapıldığını paha biçilmez kılan bir kod dışı açıklama. Bu tür bir belge, kod turuna çıkmadan önce yeni başlayanlar için okunması gereken bir şeydir . Orada bir sürü net etrafında saçmalık my-metodolojisi-de-radikal-için-docs-ahbap olduğunu ve süre olduğu olduğu bir ilk kemer doc ve gelişmekte olan kemer doc hizada olmaz doğrudur, bir düzyazı açıklama gereklidir Herkes için büyük, önemsiz olmayan bir kod tabanını hızla kavraması. İşte (zayıf) bir örnek: zxq9.com/erlmud/html/001-002_architecture.html
—
zxq9 08:51 de
@Telastyn: Bunun kodun okunup okunamayacağı ile ilgisi yok (ve umarım öyledir). Tasarım gerekçesini belgelemek kesinlikle önemlidir.
—
Orbit'teki Hafiflik Yarışları
@Telastyn: Evet, belki. Şahsen ben tek başına bir doktora yazarım. Ancak kaynak dosyaların tepesindeki yorum blokları o kadar da kötü değil.
—
Orbit'teki Hafiflik Yarışları