# Project Name

Brief description (1-2 sentences)

## Features
- Key feature 1
- Key feature 2

## Installation
```bash
npm install package-name

const lib = require('package-name');
lib.doSomething();

---

### 2. Code Comments

**When to Comment**:
- ✅ Complex algorithms
- ✅ Non-obvious decisions
- ✅ Workarounds for bugs
- ✅ Public APIs
- ❌ Self-explanatory code
- ❌ What code does (code shows that)

**Good Comments**:
```python
# Calculate tax using 2024 progressive rates
# See: https://irs.gov/tax-rates-2024
def calculate_tax(income):
    # ...

# HACK: API returns string "null" instead of null
# TODO: Remove once API v2 is deployed
if response == "null":
    response = None

# Increment i
i = i + 1  # Obvious from code

# This function adds two numbers
def add(a, b):  # Function name is clear
    return a + b

def calculate_discount(price: float, discount_pct: float) -> float:
    """
    Calculate discounted price.

    Args:
        price: Original price in dollars
        discount_pct: Discount percentage (0-100)

    Returns:
        Final price after discount

    Raises:
        ValueError: If discount_pct is not between 0 and 100

    Examples:
        >>> calculate_discount(100, 20)
        80.0
    """
    if not 0 <= discount_pct <= 100:
        raise ValueError("Discount must be between 0 and 100")
    return price * (1 - discount_pct / 100)

/**
 * Calculate discounted price
 * @param {number} price - Original price in dollars
 * @param {number} discountPct - Discount percentage (0-100)
 * @returns {number} Final price after discount
 * @throws {Error} If discountPct is not between 0 and 100
 * @example
 * calculateDiscount(100, 20) // Returns 80
 */
function calculateDiscount(price, discountPct) {
    if (discountPct < 0 || discountPct > 100) {
        throw new Error('Discount must be between 0 and 100');
    }
    return price * (1 - discountPct / 100);
}

## GET /api/users/:id

Retrieve user by ID.

### Parameters
- `id` (path, required): User ID

### Query Parameters
- `include` (optional): Comma-separated relations to include
  - Values: `profile`, `posts`, `comments`

### Response
```json
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "createdAt": "2024-01-15T10:30:00Z"
}

curl -H "Authorization: Bearer TOKEN" \
     https://api.example.com/api/users/123?include=profile

---

### 5. Architecture Documentation

**System Overview**:
```markdown
## Architecture

### High-Level Design

### Components

#### API Server
- **Technology**: Node.js + Express
- **Responsibility**: Handle HTTP requests, business logic
- **Scaling**: Horizontal (load balanced)

#### Database
- **Technology**: PostgreSQL 15
- **Responsibility**: Persistent data storage
- **Backup**: Daily automated backups

#### Cache
- **Technology**: Redis
- **Responsibility**: Session storage, API response cache
- **TTL**: 5 minutes for API responses

```python
# Code here
```

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| name      | string | yes      | User name   |

- Item 1
- Item 2
  - Sub-item 2.1

**Bold** for important terms
*Italic* for emphasis
`code` for inline code

# Project Name

One-line description

## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)

## Features
- Feature 1
- Feature 2

## Installation

### Prerequisites
- Node.js 18+
- npm or yarn

### Steps
```bash
git clone https://github.com/user/repo.git
cd repo
npm install

const lib = require('lib');
lib.doSomething();

API_KEY=your_key
DATABASE_URL=postgresql://...

npm run dev        # Start dev server
npm test          # Run tests
npm run lint      # Lint code

### CHANGELOG Template
```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/).

## [Unreleased]

### Added
- New feature X

### Changed
- Updated dependency Y

### Fixed
- Bug Z in component W

## [1.0.0] - 2024-01-15

### Added
- Initial release
- Feature A
- Feature B

### Security
- Fixed vulnerability CVE-XXXX

# Contributing Guide

Thank you for contributing!

## Code of Conduct

Be respectful and inclusive.

## How to Contribute

### Reporting Bugs
- Check existing issues first
- Use bug report template
- Include reproduction steps
- Specify environment details

### Suggesting Features
- Check roadmap and existing requests
- Use feature request template
- Explain use case and benefits

### Pull Requests

#### Before Submitting
1. Fork and create branch
2. Follow coding standards
3. Add tests
4. Update documentation
5. Run linter and tests

#### PR Guidelines
- Clear description of changes
- Link related issues
- Keep changes focused
- Update CHANGELOG.md

## Development Setup

```bash
git clone https://github.com/user/repo.git
cd repo
npm install
npm run dev

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

---

## Documentation Checklist

Before finalizing documentation:

- [ ] README exists and is complete
- [ ] Installation instructions clear
- [ ] Usage examples provided
- [ ] API documented (if applicable)
- [ ] Code has appropriate comments
- [ ] Complex logic explained
- [ ] Configuration documented
- [ ] Contributing guide exists
- [ ] License specified
- [ ] CHANGELOG maintained
- [ ] Links work correctly
- [ ] Code examples tested
- [ ] Spelling/grammar checked
- [ ] Formatting consistent

---

## Automation Tips

### Auto-Generate API Docs
```javascript
// JSDoc to Markdown
npm install -g jsdoc-to-markdown
jsdoc2md src/**/*.js > API.md

# Python: Test docstring examples
python -m doctest module.py

# Or use pytest
pytest --doctest-modules

# Pre-commit hook to check docs
#!/bin/bash
if git diff --cached --name-only | grep -q "^src/"; then
    if ! git diff --cached --name-only | grep -q "^docs/"; then
        echo "Warning: Code changed but docs not updated"
        exit 1
    fi
fi