mirror of
https://github.com/duthaho/claudekit.git
synced 2026-06-11 04:34:56 +03:00
duthaho
53 lines
1.3 KiB
Markdown
53 lines
1.3 KiB
Markdown
# Code Documentation Patterns
|
|
|
|
## Python Docstrings (Google Style)
|
|
|
|
```python
|
|
def calculate_discount(price: float, percentage: float) -> float:
|
|
"""Calculate discounted price.
|
|
|
|
Args:
|
|
price: Original price in dollars.
|
|
percentage: Discount percentage (0-100).
|
|
|
|
Returns:
|
|
The discounted price.
|
|
|
|
Raises:
|
|
ValueError: If percentage is not between 0 and 100.
|
|
|
|
Example:
|
|
>>> calculate_discount(100.0, 20)
|
|
80.0
|
|
"""
|
|
```
|
|
|
|
## TypeScript JSDoc
|
|
|
|
```typescript
|
|
/**
|
|
* Calculate discounted price.
|
|
*
|
|
* @param price - Original price in dollars
|
|
* @param percentage - Discount percentage (0-100)
|
|
* @returns The discounted price
|
|
* @throws {RangeError} If percentage is not between 0 and 100
|
|
*
|
|
* @example
|
|
* calculateDiscount(100, 20); // returns 80
|
|
*/
|
|
```
|
|
|
|
## When to Add Inline Comments
|
|
|
|
- Explain **why**, not what — `# Retry 3x because upstream API is flaky`
|
|
- Document workarounds — `// Safari doesn't support this API, fallback to...`
|
|
- Clarify non-obvious logic — `# O(1) amortized via lazy deletion`
|
|
- Mark TODOs with context — `# TODO(#123): remove after migration complete`
|
|
|
|
## When NOT to Comment
|
|
|
|
- Restating the code: `i += 1 # increment i by 1`
|
|
- Obvious function names: `def get_user_by_id` needs no docstring explaining it gets a user by ID
|
|
- Commented-out code — delete it, git has history
|