Türkçe Kod Dokümantasyonu Rehberi Skill

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

| İngilizce (kaçın) | Türkçe (tercih) | |-------------------|-----------------| | 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

| Etiket | Kullanım | |--------|----------| | ekle | Yeni özellik | | düzelt | Hata giderme | | güncelle | Mevcut özellik iyileştirme | | sil | Kod/dosya silme | | yeniden-düzenle | Davranış değiştirmeden kod temizliği | | test | Test ekleme/güncelleme | | belge | Sadece dokümantasyon | | yapılandır | Config/CI değişikliği |

Ö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 dosyasına bakın.

| İngilizce | Türkçe Karşılık | |-----------|----------------| | Authentication | Kimlik doğrulama | | Authorization | Yetkilendirme | | Deployment | Dağıtım / Kurulum | | Refactoring | Yeniden düzenleme | | Repository | Depo | | Pull Request | Birleştirme isteği | | Branch | Dal | | Merge | Birleştirme | | Dependency | Bağımlılık | | Middleware | Ara katman | | Cache | Önbellek | | Thread | İş parçacığı | | Callback | Geri çağırım | | Instance | Örnek / Nesne | | Endpoint | Uç nokta |

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

Agent Skills: Türkçe Kod Dokümantasyonu Rehberi

Install this agent skill to your local

Skill Files