vuralserhat86/skills/docs_code

💻 Docs Code

Code documentation ve changelog best practices.

---

📝 JSDoc/TSDoc

/**
 * Calculates total price including tax.
 * 
 * @param amount - Base amount before tax
 * @param taxRate - Tax rate as decimal (0.18 = 18%)
 * @returns Total amount including tax
 * 
 * @example
 * const total = calculateTotal(100, 0.18); // 118
 */
function calculateTotal(amount: number, taxRate: number): number {
  return amount * (1 + taxRate);
}

---

✅ Comment Best Practices

// ❌ What (kod zaten söylüyor)
// Increment counter by 1
counter++;

// ✅ Why (neden böyle yapıldığını açıklıyor)
// Using setTimeout to debounce API calls
setTimeout(() => saveChanges(), 500);

// ✅ Business logic
// Premium users get 20% discount (JIRA-1234)
if (user.isPremium) discount = 0.20;

---

📋 Changelog (Keep a Changelog)

## [1.2.0] - 2025-01-15

### Added
- OAuth2 authentication

### Fixed
- Login button on mobile

### Security
- Patched XSS vulnerability

---

🔗 Conventional Commits

feat(auth): add Google OAuth
fix(api): handle null response
docs(readme): add installation
refactor(utils): simplify logic

---

Docs Code v1.1 - Enhanced

🔄 Workflow

Kaynak: TSDoc Standard & Keep a Changelog

Aşama 1: Inline Documentation

• [ ] Public API: Export edilen her fonksiyon/class için TSDoc (/** ... */) yaz.
• [ ] Context: "Neden" (Why) sorusunu cevaplayan yorumlar ekle (// Optimize for ...).
• [ ] Examples: Karmaşık fonksiyonlar için @example bloğu ekle.

Aşama 2: Changelog Management

• [ ] Unreleased: Yapılan değişiklikleri anında [Unreleased] başlığı altına ekle.
• [ ] Categories: Added, Changed, Deprecated, Removed, Fixed, Security etiketlerini kullan.
• [ ] Versioning: SemVer (Maj.Min.Patch) kurallarına göre versiyonla.

Aşama 3: Commit Standards

• [ ] Format: Conventional Commits (feat:, fix:, docs:) kullan.
• [ ] Scope: Değişikliğin kapsamını belirt (feat(auth):).

Kontrol Noktaları

| Aşama | Doğrulama | |-------|-----------| | 1 | IDE'de fonksiyon üzerine gelince TSDoc çıkıyor mu? | | 2 | Changelog'da tarih formatı ISO 8601 (YYYY-MM-DD) mi? | | 3 | Commit mesajı "ne" ve "neden" sorularını cevaplıyor mu? |