Kod Kalitesi ve Ekip Standartları

Yazılı kural ihlal edilir, otomatik kural edilmez. Bu rehber ekibin kod standartlarını üç katmanda araçlara bağlıyor: editörde, commit anında ve CI'da. Google'ın kod inceleme rehberi stil konusunda stil rehberini nihai otorite sayarken, yazılım tasarımının neredeyse hiçbir zaman saf bir stil tercihi olmadığını söylüyor.¹ Stil kurallarını araca devrettiğinizde inceleme zamanı tasarıma kalır.

Üç katman

Üçü de aynı komutları çalıştırır. Fark hızları ve atlanabilirlikleri: editör ve hook size hızlı geri bildirim verir, CI ise son kapıdır.

Araç seçimi

Bu bir görüş meselesi. Önemli olan ekibin tek bir araç setinde ve tek bir ayarda anlaşması.

Prettier'ın yaklaşımı bilinçli kısıtlamaya dayanıyor: yalnızca kodu yazdırıyor, dönüştürmüyor ve önceliği davranışı aynı tutmak.⁸ Biome'a geçiş gerekçesini Web Dev Simplified'ın videosu da hız ve tek ayar üzerinden anlatıyor.⁹

Bu rehberdeki kurulum ESLint + Prettier ile, Biome için komutlar aşağıda ayrıca var. Güncel bir karşılaştırma için Elite Dev News'in ESLint, Biome ve Oxlint videosuna bakabilirsiniz.¹⁰

ESLint ve Prettier kurulumu

pnpm add -D eslint @eslint/js typescript@^6 typescript-eslint eslint-config-prettier prettier

// eslint.config.mjs
import js from '@eslint/js'
import { defineConfig, globalIgnores } from 'eslint/config'
import tseslint from 'typescript-eslint'
import prettier from 'eslint-config-prettier'

export default defineConfig([
  globalIgnores(['dist/', '.next/', 'coverage/']),
  {
    files: ['**/*.{js,mjs,ts,tsx}'],
    extends: [js.configs.recommended, tseslint.configs.recommended],
  },
  prettier,
])

• ESLint eslint.config.js, .mjs veya .cjs dosyasını arar. Dosya bir config nesneleri dizisi dışa aktarır, defineConfig yardımcısı eslint/config paketinden gelir.¹²

• Aynı dosyayı eşleyen nesneler birleşir, çakışmada sonraki nesne kazanır.¹² Bu yüzden prettier en sonda durur: çakışan biçim kurallarını son söz olarak kapatır.

• Tek anahtarı ignores olan nesne tüm yapılandırmaya uygulanır. globalIgnores() bunu açık hâle getirir. node_modules ve .git zaten yok sayılır.¹²

• Tip bilgisi kullanan kurallar ayrı bir kurulum gerektirir, typescript-eslint'in Typed Linting sayfasında anlatılıyor.¹³

• Mimari sınırları da burada zorlayabilirsiniz. import/no-restricted-paths zone'ları Component ve Kod Organizasyonu rehberinde.

// .prettierrc.json
{ "semi": false, "singleQuote": true }

// package.json (scripts)
{
  "scripts": {
    "lint": "eslint .",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "check-types": "tsc --noEmit"
  }
}

Hatalı bir dosyada pnpm lint şöyle bir çıktı verir:

src/bad.ts
  1:7   error  'unused' is assigned a value but never used  @typescript-eslint/no-unused-vars
  2:17  error  Unexpected any. Specify a different type     @typescript-eslint/no-explicit-any

Biome ile

pnpm add -D -E @biomejs/biome   # -E: sürümü sabitler, herkes aynı sürümü kullanır
pnpm exec biome init
pnpm exec biome check           # formatter + linter + import düzenleme
pnpm exec biome check --write   # güvenli düzeltmeleri uygular
pnpm exec biome ci              # CI için

Mevcut projeyi taşıyorsanız biome migrate eslint --write ve biome migrate prettier --write komutları kuralları ve ayarları çevirir. Taşıma yalnızca birebir aynı kuralları alır, --include-inspired ile Biome'un ilham aldığı kuralları da ekleyebilirsiniz. Eklenti kuralları elle taşınır ve Prettier çıktısı birebir aynı olmayabilir.⁶ Sonra ESLint, Prettier ve eklentilerini kaldırın.⁶

Commit öncesi kontrol: Husky ve lint-staged

Husky git hook'larını projeye bağlar, lint-staged ise yalnızca commit'e giren dosyalar üzerinde komut çalıştırır. Linter tüm projeyi taramaz, böylece hızlı kalır.²¹⁴

pnpm add -D husky lint-staged
pnpm exec husky init

husky init .husky/pre-commit dosyasını oluşturur ve package.json içindeki prepare script'ini günceller.¹⁵ Hook'un içeriğini lint-staged ile değiştirin:

# .husky/pre-commit
pnpm exec lint-staged

// package.json
{
  "lint-staged": {
    "*.{js,mjs,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,css}": "prettier --write"
  }
}

lint-staged, eşleşen staged dosya adlarını komutun sonuna argüman olarak ekler. eslint --fix komutu eslint --fix a.ts b.ts olarak çalışır.¹⁴ Hatalı bir dosyayı commit etmeyi denerseniz commit reddedilir:

✖ eslint --fix:
  3:17  error  Unexpected any. Specify a different type  @typescript-eslint/no-explicit-any
husky - pre-commit script failed (code 1)

Commit mesajı kuralları

Conventional Commits mesajı sabit bir yapıya oturtur: <type>[optional scope]: <description>, ardından isteğe bağlı gövde ve alt bilgi.¹⁶

docs, chore gibi diğer türler serbesttir ama sürümleme açısından özel anlamları yoktur.¹⁶

pnpm add -D @commitlint/cli @commitlint/config-conventional

// commitlint.config.js
export default { extends: ['@commitlint/config-conventional'] }

# .husky/commit-msg
pnpm exec commitlint --edit $1

commitlint'in Husky v9 rehberi aynı hook'u npx --no -- commitlint --edit $1 olarak yazıyor, pnpm exec bunun pnpm karşılığı.¹⁷ Kurallara uymayan mesaj reddedilir:

$ git commit -m "added stuff"
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]
husky - commit-msg script failed (code 1)

git commit -m "feat(cart): add ok constant" ise geçer. How Dev You'nun videosu bu kurulumu uçtan uca gösteriyor.¹⁸

CI: son kapı

Hook'lar atlanabildiği için aynı kontroller CI'da da çalışmalı:

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
  push:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v6
      - name: Install pnpm and Node.js
        uses: pnpm/setup@c9883cc79df532ad1a7b81bf9ab944ceb090d65c # v2.0.0
        with:
          runtime: node@24
          cache: true
      - run: pnpm lint
      - run: pnpm format:check
      - run: pnpm check-types

• pnpm/setup pnpm'i, Node.js'i kurar ve bağımlılıkları yükler. cache: true pnpm store'unu önbelleğe alır. pnpm CI ortamında kilit dosyasını otomatik dondurur, ayrıca bayrak vermeniz gerekmez.¹⁹

• pnpm sürümü package.json'daki packageManager alanından okunur, workflow'u güncellemeniz gerekmez.¹⁹

• Pinlenmiş pnpm/setup satırı ve diğer sürümler pnpm dokümanındaki örnekten alındı.¹⁹ Siz de eylemleri bir commit SHA'sına sabitleyebilirsiniz.

Kontrolün gerçekten kapı olması için GitHub'da required status checks açın. Zorunlu kontroller successful, skipped veya neutral olmadan birleştirme yapılamaz. İş adları tüm workflow'larda benzersiz olmalı, yoksa kontrol sonuçları belirsizleşir ve PR'lar bloke olabilir.³ Anthony Fu'nun videosu bu hattı PR başına çalışan bir lint.yml olarak kuruyor, yerelde denemek için de Docker tabanlı act aracını gösteriyor.²

Monorepo'da CI

Monorepo kullanıyorsanız her PR'da her şeyi çalıştırmanız gerekmez:

      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      # ... pnpm/setup adımı
      - run: pnpm turbo run lint check-types --affected
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}

--affected yalnızca değişiklikten etkilenen paketlerde görev çalıştırır. Kaynak kontrol geçmişi gerektirdiği için sığ (shallow) bir checkout'ta tüm paketler değişmiş sayılır, bu yüzden fetch-depth: 0 ile geçmişi çekin.²⁰ TURBO_TOKEN ve TURBO_TEAM Remote Cache'e erişimi sağlar.²⁰

Ekip standartları ve kod inceleme

Otomasyon biçimi çözdükten sonra insan incelemesi tasarıma bakar. Google'ın rehberinden pratik çıkarımlar:¹

• Küçük ama doğru ilerleyin: İnceleyen, kod sağlığını kesin olarak iyileştiren bir değişikliği mükemmel olmasa da onaylamaya meyilli olmalı. "Mükemmel kod yoktur, yalnızca daha iyi kod vardır."

• Küçük notları işaretleyin: Zorunlu olmayan yorumlara Nit: öneki koyun, yazar yok sayabilsin.

• Stil ile tasarımı ayırın: Stil rehberinin kapsamadığı saf stil tercihlerinde mevcut koda uyun, aksi hâlde yazara bırakın. Tasarım konularında mühendislik ilkelerine bakın.

• Anlaşmazlıkta sıraya girin: Önce uzlaşı, sonra yüz yüze görüşme, olmazsa teknik lider veya mühendislik yöneticisi. PR beklemede kalmasın.

Kendin dene

1. ESLint ve Prettier'ı kurun. Kasıtlı olarak any ve kullanılmayan bir değişken yazıp pnpm lint çalıştırın.

2. Husky ve lint-staged'i ekleyin, hatalı dosyayı commit etmeyi deneyin ve reddedildiğini görün.

3. commitlint'i ekleyin. git commit -m "added stuff" komutunun reddedildiğini, feat(cart): add item komutunun geçtiğini doğrulayın.

4. CI workflow'unu ekleyin, hatalı bir PR açın ve kontrolün kırmızıya düştüğünü görün. Sonra branch protection'da kontrolü zorunlu yapın.

5. Aynı projeyi biome migrate ile Biome'a taşıyıp hız ve çıktı farkına bakın.

6. Anthony Fu'nun Lint Like a Senior Developer videosunu ve How Dev You'nun commitlint videosunu izleyin.²¹⁸