Python Kodunu Belgelendirme: Pratik Rehber ve İpuçları

Python kodunu iyi belgelendirmek, sadece şu an için değil gelecekte de kendine ve ekibine büyük fayda sağlar. Kötü belgelendirilmiş bir kod, üç ay sonra sen bile 'bu ne yapıyordu?' diye sorgulamaya başlarsın.

Belgelendirmenin temel taşları üç şeye dayanır: docstring'ler, inline yorumlar ve type hint'ler. Docstring'ler fonksiyon, sınıf ve modüller için resmi açıklamalar sağlar. Python'da bu, üç tırnak ile yazılan çok satırlı metinlerdir ve `help()` fonksiyonu ya da IDE'ler tarafından otomatik okunur.

1def hesapla_faiz(anapara, oran, yil):
2"""
3Basit faiz hesaplar.
4
5Args:
6anapara (float): Yatırılan miktar
7oran (float): Yıllık faiz oranı (%)
8yil (int): Yıl sayısı
9
10Returns:
11float: Toplam faiz miktarı
12"""
13return anapara * (oran / 100) * yil

Type hint'ler ise parametrelerin ve dönüş değerinin türünü belirtir. Bu, hem okuyucuya hem de linter araçlarına hangi veri tipiyle çalıştığını söyler. Yukarıdaki örneği type hint'lerle yazarsak daha profesyonel görünür:

1def hesapla_faiz(anapara: float, oran: float, yil: int) -> float:
2"""Basit faiz hesaplar."""
3return anapara * (oran / 100) * yil

Inline yorumlar ise karmaşık algoritmaların veya garip çözümlerin neden öyle yapıldığını açıklamak için kullanılır. Ancak 'x = 5 # x'e 5 ata' gibi açık seçik şeyler yorumlamayın; kodun kendisi zaten bunu söylüyor.

Bir proje büyüdüğünde, Sphinx veya MkDocs gibi araçlarla otomatik dokümantasyon üretebilirsin. Bu araçlar docstring'lerini alıp güzel HTML sayfalarına dönüştürür. Açık kaynak projelerin çoğu bu yöntemi kullanır.

Belgelendirme sadece 'başkaları anlasın' diye değildir; altı ay sonra kendi kodunu okuduğunda, geçmiş kendine teşekkür edecek. Kötü belgelendirme teknik borç biriktirir ve sonunda refactor etmek çok daha pahalı olur.