Python Yorum Satırları: Tek Satırlık, Çok Satırlı ve Docstring'ler

Yorumlar İnsanlar İçindir

Python yorumları görmezden gelir. Mesele bundan ibaret. Yorum olarak işaretlediğin her şey yorumlayıcıya görünmez olur — sadece kodu okuyan kişi için oradadır, o da genellikle altı ay sonra geçmiş sen'in ne düşündüğünü merak eden gelecek sen olursun.

Ama kodun bariz şekilde ne yaptığını tekrarlayan bir yorum yazmaya değmez. En iyi yorumlar neden'i açıklar — bir kısıt, bir geçici çözüm, koddan kendiliğinden anlaşılmayan bir karar. Ne olduğunu kod zaten anlatıyor.

# ile Tek Satırlık Yorumlar

Temel hali bir # ve ardından notun:

Bir satırın sonuna kısa bir yorum da ekleyebilirsin. Kural olarak # öncesinde en az iki boşluk bırak:

Python, string'in dışındaki herhangi bir # işaretini görür ve satırın geri kalanını yorum olarak ele alır. "String dışında" kısmı önemli: tırnak içindeki # sadece bir karakterdir.

String içindeki #section-2 URL'nin parçası. Python sadece string kapandıktan sonraki # için "yorum" moduna geçer.

Birden Fazla Satırı Yoruma Alma

Python'un /* */ blok yorumu yoktur. Birkaç satırı atlamak için her birinin başına # koyarsın:

Bu # işaretlerini neredeyse hiç elle yazmazsın. Her düzgün editörde seçili her satıra # ekleyip kaldıran bir "satır yorumu aç/kapa" kısayolu vardır:

• VS Code: Cmd + / (macOS) ya da Ctrl + / (Windows/Linux)
• PyCharm: Cmd + / ya da Ctrl + /
• Vim: eklentilerine bağlı; vim-commentary tek satır için gcc, seçim için gc atar.

Editöründeki kısayolu bir kere öğren; "bu bloğu yoruma alıp bir şey denemek" tek tuş basışına dönüşür.

Üçlü Tırnaklı String Hilesi (ve Neden Gerçek Bir Yorum Olmadığı)

Bazen şuna benzer kodlar görürsün:

Teknik olarak bu, atılan bir string ifadesidir. Python onu ayrıştırır, değerlendirir ve sonucu atar. Yorum gibi davranır ama yorum değildir. Stilistik olarak, bu sadece bir yerde iyi bir fikir: docstring olarak.

Docstring'ler: Üçlü Tırnakların Asıl Yeri

Bir docstring, bir fonksiyonun, sınıfın veya modülün tam ilk ifadesi olarak yerleştirilmiş üçlü tırnaklı bir string'dir. Python onu belge olarak tanır ve çalışma zamanında help() fonksiyonu ile __doc__ özniteliği aracılığıyla erişilebilir kılar:

Docstring'leri değerli kılan iki şey var:

1. IDE'ler, help() ve belge üreticileri gibi araçlar onları otomatik olarak okur. Fonksiyonun üstündeki bir yorum bunların hiçbirini sağlamaz.
2. Fonksiyonu çağrıldığı noktada anlatırlar — birisi editörde discount(...) üzerine geldiğinde docstring bir ipucu olarak belirir.

Bir docstring'de neler olacağına dair bir kural var (PEP 257): ilk satırda tek satırlık özet, boş bir satır, ardından gerekirse daha uzun bir açıklama. İlk gün tam formata takılma — sade bir tek satırlık özet bile hiç docstring olmamasından çok daha iyidir.

İyi Yorumlar Aslında Ne Söyler

İleride çok baş ağrısından kurtaran birkaç ilke:

• Ne yerine neden'i anlatmayı tercih et. # Kullanıcılar üzerinde döngü kur gürültüdür; # 503'te tekrar dene — Redis deploy sırasında bazen ölüyor altın değerindedir.
• Kodu değiştirdiğinde yorumları da güncelle. Yanlış bir yorum hiç yorumdan daha kötüdür. Bayat yorumlar gelecekteki okuyucuyu aktif olarak yanıltır.
• Kodu yoruma alıp bırakma. Gerek yoksa sil. Versiyon kontrolü hatırlar. Yoruma alınmış bloklarla dolu bir dosya hızla güvenilmez hale gelir.
• Apaçık olanı atla. x = x + 1 # x'i artır hiçbir şey katmaz.

Sonuç

Yorumları yazmak ücretsiz, atlamak ucuzdur. Okuyucunun sana teşekkür edeceği bir not bırakıyorsan onlara başvur — bir şeyin neden işe yaradığının ince sebebi, bir issue'ya bağlantı, bir uç durum uyarısı. Fonksiyon ya da sınıf tanımlarken docstring kullan. Geri kalanda konuşmayı açıklayıcı isimler ve küçük fonksiyonlara bırak.

Artık bir Python dosyasını okumak ve yazmak için ihtiyacın olan her şey elinde. Bir sonraki bölüm, dilin gerçekten bir şeyler yapmaya başladığı yer: değişkenler, veri tipleri ve Python'un tutabileceği değerler.