Yorumlar Üzerine Bir Yorum

Üniversitedeki ilk programlama dersimde öğretmenim iki BASIC kodlama sayfası dağıttı. Tahtada, ödevde "Bir program yazın ve ortalama 10 bowling skoru yazın" yazıyordu. Sonra öğretmen odadan çıktı. Bu ne kadar zor olabilir? Son çözümümü hatırlamıyorum ama içinde bir 'FOR/NEXT' döngüsü olduğundan ve toplamda 15 satırdan uzun olamayacağından eminim. Kodlama sayfaları, bunu okuyan çocuklar için, evet, aslında bir bilgisayara girmeden önce uzunlamasına kod yazardık, her biri yaklaşık 70 satırlık koda izin verirdi. Öğretmenin bize neden iki sayfa vereceği konusunda kafam çok karıştı. El yazım her zaman acımasız olduğu için, stil için birkaç ekstra puan almayı umarak ikincisini kodumu çok düzgün bir şekilde yeniden kopyalamak için kullandım.

Şaşırtıcı bir şekilde, bir sonraki dersin başında ödevi geri aldığımda, zar zor geçen bir not aldım. (Üniversitede geçirdiğim zamanın geri kalanında benim için bir kehanet olacaktı.) Özenle kopyalanmış kodumun üst kısmına karalanmış, "Yorum yok mu?"

Öğretmenin de benim de programın ne yapması gerektiğini bilmemiz yeterli değildi. Görevin amacının bir kısmı, kodumun arkamdan gelen bir sonraki programcıya kendini açıklaması gerektiğini öğretmekti. Bu unutmadığım bir ders.

Yorumlar kötü değil. Temel dallanma veya döngü yapıları kadar programlama için gereklidirler. Çoğu modern dilde, otomatik olarak bir API belgesi oluşturmak için uygun şekilde biçimlendirilmiş yorumları ayrıştıracak javadoc'a benzer bir araç bulunur. Bu çok iyi bir başlangıç, ancak neredeyse yeterli değil. Kodunuzun içinde, kodun ne yapması gerektiğine dair açıklamalar olmalıdır. Eski atasözüyle kodlama yapmak, "Yazması zorsa, okuması da zor olur", müşterinize, işvereninize, meslektaşlarınıza ve gelecekteki kendinize zarar verir.

Öte yandan, yorumunuzda çok ileri gidebilirsiniz. Yorumlarınızın kodunuzu netleştirdiğinden emin olun, ancak onu gizlemeyin. Kodun neyi başarması gerektiğini açıklayan ilgili yorumları kodunuza serpiştirin. Başlık yorumlarınız, herhangi bir programcıya kodunuzu okumak zorunda kalmadan kullanmak için yeterli bilgi verirken, satır içi yorumlarınız bir sonraki geliştiriciye onu düzeltmede veya genişletmede yardımcı olmalıdır.

Bir işte, üstümdekilerin verdiği bir tasarım kararına katılmadım. Genç programcıların sık sık yaptığı gibi, kendimi oldukça tuhaf hissederek, tasarımlarını kullanmamı söyleyen e-posta metnini dosyanın başlık yorum bloğuna yapıştırdım. Bu mağazadaki yöneticilerin, işlendiğinde kodu gerçekten inceledikleri ortaya çıktı. Bu benim kariyer sınırlayıcı hareket terimiyle ilk tanışmamdı.

Cal Evans Tarafından