Türkçe Kod Dokümantasyonu Rehberi

Bu skill, Türkçe yazılım projelerinde tutarlı, okunabilir ve profesyonel dokümantasyon yazmanı sağlar.

1. Yorum Satırı Standartları

Genel Kurallar

• Yorumlar Türkçe yazılır, yabancı kelimeler italik veya tırnak içinde gösterilir.
• Yorum satırları büyük harfle başlar, nokta ile biter.
• Kod ne yaptığını değil, neden yaptığını açıklar.

Python Örneği

# Kullanıcı oturumunu doğrula ve yetki seviyesini belirle.
def oturum_dogrula(kullanici_id: int) -> dict:
    """
    Verilen kullanıcı kimliğine göre oturum bilgilerini döndürür.

    Args:
        kullanici_id: Veritabanındaki benzersiz kullanıcı numarası.

    Returns:
        Kullanıcı bilgisi ve yetki seviyesini içeren sözlük.

    Raises:
        KullaniciBulunamadi: Kullanıcı veritabanında yoksa.
    """
    ...

JavaScript / TypeScript Örneği

/**
 * Sepetteki ürünlerin toplam fiyatını hesaplar.
 * KDV dahil tutar için `kdvDahilFiyat()` fonksiyonunu kullan.
 *
 * @param urunler - Fiyat bilgisi içeren ürün dizisi
 * @returns Toplam fiyat (kuruş cinsinden, virgülsüz tam sayı)
 */
function toplamFiyatHesapla(urunler: Urun[]): number {
    // Boş sepet kontrolü — backend doğrulamasına güvenmiyoruz.
    if (urunler.length === 0) return 0;
    return urunler.reduce((toplam, urun) => toplam + urun.fiyat, 0);
}

Go Örneği

// SiparisOlustur yeni bir sipariş kaydı oluşturur ve veritabanına ekler.
// Stok kontrolü bu fonksiyon içinde yapılmaz; çağırmadan önce StokKontrol() çalıştır.
func SiparisOlustur(ctx context.Context, istek SiparisIstegi) (*Siparis, error) {
    ...
}

2. Değişken ve Fonksiyon İsimlendirme

Türkçe mi, İngilizce mi?

• Tercih: Projenin diline göre tutarlı ol. Karma kullanımdan kaçın.
• Türkçe kullan: İş mantığı (domain) değişkenlerinde —

  musteri

  ,

  siparis

  ,

  fatura

  .
• İngilizce bırak: Framework/kütüphane terimleri —

  request

  ,

  response

  ,

  callback

  ,

  index

  .

Adlandırma Örnekleri

user

kullanici

order

siparis

invoice

fatura

product

urun

cart

sepet

address

adres

payment

odeme

employee

calisan

company

sirket

report

rapor

Türkçe Karakter Uyarısı

Dil destekleyen ortamlarda (Python 3, modern JS/TS) Türkçe karakter kullanılabilir:

müşteri_adı = "Ali"   # Geçerli Python 3
ürün_listesi = []     # Geçerli Python 3

Ancak terminal uyumsuzluğu riski nedeniyle ASCII karşılıklarını tercih et:

musteri_adi = "Ali"   # Daha güvenli
urun_listesi = []     # Daha güvenli

3. Commit Mesajı Yazımı

Format

<tür>: <kısa açıklama> (max 72 karakter)

<detay — opsiyonel, neden değiştirildi>

Refs: #123

Tür Etiketleri

ekle

düzelt

güncelle

sil

yeniden-düzenle

test

belge

yapılandır

Örnekler

ekle: kullanıcı profil fotoğrafı yükleme özelliği

Cloudinary entegrasyonu ile resim yükleme ve boyutlandırma eklendi.
5MB sınırı ve JPEG/PNG/WebP formatı destekleniyor.

Refs: #87

düzelt: boş sepette toplam fiyat hesabı sıfır gösterilmiyor

yeniden-düzenle: fatura modülünü servis katmanına taşı

4. README.md Şablonu

# Proje Adı

Projenin ne yaptığını tek cümlede açıkla.

## Kurulum

\```bash
pip install proje-adi
# veya
npm install proje-adi
\```

## Hızlı Başlangıç

\```python
from proje import AnaModul

modul = AnaModul(api_anahtari="...")
sonuc = modul.calistir()
print(sonuc)
\```

## Özellikler

- **Özellik 1:** Açıklama
- **Özellik 2:** Açıklama

## Yapılandırma

| Parametre | Tür | Varsayılan | Açıklama |
|-----------|-----|-----------|----------|
| `api_anahtari` | `str` | — | Zorunlu |
| `zaman_asimi` | `int` | `30` | Saniye cinsinden |

## Katkı Sağlama

1. Fork oluştur
2. Özellik dalı aç: `git checkout -b ozellik/yeni-ozellik`
3. Değişikliklerini commit et: `ekle: yeni özellik açıklaması`
4. Pull Request aç

## Lisans

MIT — Ayrıntılar için [LICENSE](LICENSE) dosyasına bakın.

5. Hata Mesajları ve Log Yazımı

Türkçe Hata Mesajları

# Kötü — İngilizce hata, Türkçe projede tutarsız
raise ValueError("User not found")

# İyi — Türkçe ve açıklayıcı
raise KullaniciBulunamadi(f"'{kullanici_id}' numaralı kullanıcı sistemde kayıtlı değil.")

Log Seviyeleri ve Türkçe Kullanım

import logging

logger = logging.getLogger(__name__)

logger.debug("Oturum doğrulama başlatıldı. kullanici_id=%s", kullanici_id)
logger.info("Sipariş oluşturuldu. siparis_no=%s tutar=%s", siparis.no, siparis.tutar)
logger.warning("Stok azalıyor. urun_id=%s kalan=%d", urun.id, urun.stok)
logger.error("Ödeme işlemi başarısız. hata=%s", str(hata))

6. Teknik Terim Hızlı Referans

Tam liste için

references/teknik-terimler.md

7. Kontrol Listesi

Kodu göndermeden önce:

• Yorum satırları Türkçe ve nokta ile bitiyor
• Değişken isimleri proje diline göre tutarlı
• Commit mesajı

  <tür>: <açıklama>

  formatında
• README.md güncel
• Hata mesajları kullanıcıya anlamlı
• Log mesajları yeterli bağlam içeriyor