Cevap.

Konunun Tarihçesi

Python'da, erken sürümlerden beri kodun docstring ile belgelendirilmesi teşvik edilmektedir. Python 3.5'te (PEP 484) tür anahatları (type hints) desteği eklenerek okunabilirlik artırılmış ve tür analizörlerinin (örneğin, mypy, pyright vb.) desteklenmesi sağlanmıştır. Böylece, fonksiyonların ve sınıfların tanımında belgelendirme ile tip belirleme birleştirilebilir.

Problem

Tür anahatları olmadan, bir işlevin ne ile çalıştığını ve ondan ne beklenmesi gerektiğini hızlıca anlamak zorlaşır. İyi bir docstring eksikliği, arayüzün yanlış anlaşılmasına ve kullanım hatalarına yol açar. Tür anahatları veya docstrings yanlış kullanıldığında, bu statik analiz için engel olur ve kodun desteklenmesini zorlaştırır.

Çözüm

Fonksiyonun amacını, parametrelerini ve sonucunu belgelendirmek için çok satırlı docstring'ler kullanın ve argümanların ve dönüş değerinin türlerini açıkça belirtmek için type hints kullanın.

Kod örneği:

def add_numbers(a: int, b: int) -> int:
    """
    İki tamsayıyı toplar ve sonucu döndürür.

    :param a: İlk terim, int
    :param b: İkinci terim, int
    :return: Toplam, int
    """
    return a + b

Ana özellikler:

Docstring, doc içinde saklanır ve IDE, help() ve otomatik belge üreticileri için erişilebilir.
Tür anahatları, annotations üzerinden erişilebilir; kodun çalışmasını etkilemez, yalnızca analiz için kullanılır.
Birlikte kullanımı, geniş ölçekli destek ve yeni programcıların eğitimini kolaylaştırır.

Alttan Gelen Sorular.

Tür anahatları, programın çalışmasını etkileyebilir mi?

Hayır. Tür anahatları (type hints), Python yorumlayıcısı tarafından çalıştırma zamanında kontrol edilmez ve sadece analizörler ve IDE'ler için, ayrıca belge otomasyonu için kullanılır. Sıfır çalışma zamanı hatası oluştururlar ve her zaman isteğe bağlıdırlar.

Parametre değerlerini sınırlamak için tür anahatları kullanılabilir mi?

Hayır. Örneğin, x: int ifadesinin, pratikte başka bir tür değerin geçmesine engel olmadığıdır. Bunun için çalışma zamanı kontrolleri (assert/isinstance) kullanabilirsiniz, ancak type hints bunu otomatik olarak doğrulamaz.

# type: ... açıklamaları yerine yorumlar kullanabilir miyiz? Bunun için ne gereklidir?

Evet, bu Python 2 ile uyumluluk veya eski kod tabanları için gerekebiliyorsa kabul edilir. Örneğin:

def foo(x, y):     # type: (int, str) -> bool
    pass

Bu, mypy ve benzeri araçlar tarafından modern sözdizimi ile aynı şekilde anlaşılır, ancak yeni projelerde standart anahatları kullanmak daha iyidir.

Tipik Hatalar ve Antipaterler

Kamuya açık işlevlerin ve sınıfların docstring'i olmaması veya boş olması
Yanlış tür belirtilmesi — örneğin, List yerine list veya türlerdeki yazım hataları (özellikle karmaşık koleksiyonlarla)
Belgelendirme güncellenmeden type hints kullanılması ve bunun tersi.

Gerçek Hayat Örneği

Olumsuz Durum

Büyük bir projede fonksiyonlar docstring ve type hints ile donatılmamış — geliştirici çok zaman harcayarak inceleme ve hata ayıklama yapıyor, sıklıkla türler ve giriş verilerinin anlamında yanlışlıklar yapıyor.

Artılar:

Başlangıçta hızlı kod yazma

Eksiler:

Bakımda büyük zorluklar, yeni çalışanların uyum süreci oldukça uzun
Hataları yakalamak zor, parametre türleri karıştığında.

Olumlu Durum

Tüm kamuya açık işlevlerde ayrıntılı docstring ve doğru type hints bulunuyor, bu da IDE'ler ve analizörlerin tür hatalarını hızlı bir şekilde bulmasını ve API dokümantasyonunu otomatik olarak oluşturmasını sağlıyor.