diegosouzapw Code Documentation Skill
Overview
This skill provides guidelines for writing effective code documentation that improves maintainability, onboarding, and collaboration.
Documentation Levels
1. Code Comments (inline)
2. Function/Method Documentation
3. Module/File Documentation
4. Architecture Documentation
5. API Documentation
6. README and Guides
Code Comments
1. When to Comment
// ✅ DO: Explain WHY, not WHAT
// Cache for 5 minutes to reduce database load during high traffic
var userCache = cache.New(5*time.Minute, 10*time.Minute)
// ❌ DON'T: State the obvious
// This function adds two numbers
func add(a, b int) int {
return a + b
}
// ✅ DO: Explain complex logic
// Using two-phase commit to ensure consistency between
// payment service and inventory service. If payment succeeds
// but inventory fails, we rollback both.
func processOrder(order Order) error {
// ...
}
// ✅ DO: Document workarounds and hacks
// TODO: Remove this workaround once API v2 is deployed
// See: https://github.com/org/repo/issues/123
func legacyWorkaround() {
// ...
}
2. Comment Formats
// Single line comment for brief explanations
/*
Multi-line comment for longer explanations
or temporarily disabled code
*/
// Section comments for organizing code
// ============================================
// SECTION: User Management
// ============================================
// MARK: - Validation (Swift style)
// region Authentication (C# style)
// endregion
Function/Method Documentation
1. Go (GoDoc)
// Package user provides user management functionality.
//
// This package handles user creation, authentication,
// and profile management.
package user
// CreateUser creates a new user in the system.
//
// Parameters:
// - ctx: Context for cancellation and timeouts
// - req: User creation request with validation
//
// Returns:
// - *User: Created user with generated ID
// - error: ValidationError if input is invalid,
// ConflictError if email already exists
//
// Example:
//
// user, err := CreateUser(ctx, CreateUserRequest{
// Email: "user@example.com",
// Name: "John Doe",
// })
//
// See: https://docs.example.com/api/users
func CreateUser(ctx context.Context, req CreateUserRequest) (*User, error) {
// Implementation
}
// IsValidEmail checks if the given string is a valid email address.
// It follows RFC 5322 standards.
func IsValidEmail(email string) bool {
// Implementation
}
2. TypeScript/JSDoc
/**
* Creates a new user in the system.
*
* @param {CreateUserRequest} params - User creation parameters
* @param {string} params.email - User's email address
* @param {string} params.name - User's full name
* @param {number} [params.age] - User's age (optional)
* @returns {Promise<User>} The created user
* @throws {ValidationError} When input is invalid
* @throws {ConflictError} When email already exists
*
* @example
* ```typescript
* const user = await createUser({
* email: 'user@example.com',
* name: 'John Doe',
* age: 25
* });
* ```
*
* @see {@link https://docs.example.com/api/users|API Documentation}
*/
async function createUser(params: CreateUserRequest): Promise<User> {
// Implementation
}
/**
* User role in the system.
* @readonly
* @enum {string}
*/
const UserRole = {
/** Regular user with standard permissions */
USER: 'user',
/** Administrator with full access */
ADMIN: 'admin',
/** Moderator with content management rights */
MODERATOR: 'moderator'
} as const;
3. Rust (RustDoc)
//! User management module
//!
//! This module provides functionality for creating,
//! updating, and deleting users.
/// Creates a new user in the system.
///
/// # Arguments
///
/// * `email` - User's email address
/// * `name` - User's full name
///
/// # Returns
///
/// Returns `Ok(User)` on success, or `Err(UserError)` if:
/// - Email is invalid
/// - Email already exists
/// - Name is empty
///
/// # Examples
///
/// ```
/// use myapp::user::create_user;
///
/// let user = create_user("user@example.com", "John Doe")?;
/// assert_eq!(user.name, "John Doe");
/// ```
///
/// # Errors
///
/// This function will return an error if the email is invalid
/// or already exists in the database.
pub fn create_user(email: &str, name: &str) -> Result<User, UserError> {
// Implementation
}
/// Checks if the given email is valid.
///
/// Returns `true` if the email follows RFC 5322 standards.
pub fn is_valid_email(email: &str) -> bool {
// Implementation
}
Documentation Standards
1. README Template
# Project Name
Brief description of what this project does.
## Features
- Feature 1
- Feature 2
- Feature 3
## Installation
\`\`\`bash
# Clone the repository
git clone https://github.com/org/repo.git
cd repo
# Install dependencies
npm install
# Set up environment
cp .env.example .env
# Edit .env with your configuration
\`\`\`
## Usage
\`\`\`bash
# Start development server
npm run dev
# Build for production
npm run build
# Run tests
npm test
\`\`\`
## API Documentation
See [API Docs](./docs/API.md) for detailed API documentation.
## Architecture
See [Architecture Guide](./docs/ARCHITECTURE.md) for system design details.
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines.
## License
[MIT](./LICENSE)
2. Architecture Decision Records (ADRs)
# ADR 001: Use PostgreSQL as Primary Database
## Status
Accepted
## Context
We need to choose a database for storing user data and application state.
Requirements:
- ACID compliance
- JSON support for flexible schemas
- Full-text search
- Geospatial queries
## Decision
We will use PostgreSQL as our primary database.
## Consequences
### Positive
- Strong data integrity
- Rich feature set (JSON, FTS, GIS)
- Excellent documentation
- Wide tool support
### Negative
- More complex setup than SQLite
- Requires connection pooling
- Horizontal scaling is complex
## Alternatives Considered
- MySQL: Good, but lacks some advanced features
- MongoDB: Flexible schema, but weaker consistency
- SQLite: Great for development, not for production scale
## References
- [PostgreSQL Documentation](https://postgresql.org/docs)
- [Comparison with MySQL](https://example.com/comparison)
3. Inline Documentation Standards
// Constants should document their purpose and values
const (
// DefaultTimeout is the default HTTP request timeout.
// It balances responsiveness with reliability.
DefaultTimeout = 30 * time.Second
// MaxRetries is the maximum number of retry attempts.
// This prevents infinite loops while allowing recovery
// from transient failures.
MaxRetries = 3
)
// Variables should document their use
var (
// ErrNotFound is returned when a requested resource
// does not exist in the database.
ErrNotFound = errors.New("resource not found")
// dbPool is the global database connection pool.
// It is initialized once in init() and should not
// be reassigned.
dbPool *sql.DB
)
// Types should document their purpose and usage
type UserRepository interface {
// Create persists a new user to the database.
// It returns ErrDuplicateEmail if the email already exists.
Create(ctx context.Context, user *User) error
// GetByID retrieves a user by their unique identifier.
// Returns ErrNotFound if no user exists with the given ID.
GetByID(ctx context.Context, id string) (*User, error)
// Update modifies an existing user's data.
// All fields except ID can be updated.
Update(ctx context.Context, user *User) error
// Delete permanently removes a user from the database.
// This operation cannot be undone.
Delete(ctx context.Context, id string) error
}
Code Examples in Documentation
1. Runnable Examples (Go)
package user_test
import (
"context"
"fmt"
"log"
"github.com/org/repo/user"
)
// ExampleCreateUser demonstrates creating a new user.
func ExampleCreateUser() {
ctx := context.Background()
newUser, err := user.CreateUser(ctx, user.CreateUserRequest{
Email: "user@example.com",
Name: "John Doe",
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created user: %s\n", newUser.Name)
// Output: Created user: John Doe
}
2. Doctests (Python)
def calculate_total(items):
"""
Calculate the total price of a list of items.
Args:
items: List of items with price and quantity
Returns:
Total price as a float
Example:
>>> items = [
... {'price': 10.0, 'quantity': 2},
... {'price': 5.0, 'quantity': 3}
... ]
>>> calculate_total(items)
35.0
"""
return sum(item['price'] * item['quantity'] for item in items)
Documentation Tools
1. Static Documentation Generators
# Go
# Generate documentation
godoc -http=:6060
# TypeScript
# Generate TypeDoc
typedoc --out docs src
# Rust
# Generate RustDoc
cargo doc --open
# Python
# Generate Sphinx docs
sphinx-build -b html docs docs/_build
2. Documentation Testing
# Go: Test examples
go test -v -run Example
# Rust: Test documentation
cargo test --doc
# Python: Test docstrings
python -m doctest myfile.py
Best Practices
DO:
- ✅ Document public APIs thoroughly
- ✅ Include code examples
- ✅ Document parameters and return values
- ✅ Document error conditions
- ✅ Keep documentation up-to-date
- ✅ Use consistent formatting
- ✅ Document why, not just what
- ✅ Cross-reference related documentation
DON'T:
- ❌ Document private/internal functions (unless complex)
- ❌ Repeat code in comments
- ❌ Use outdated examples
- ❌ Write novels in comments
- ❌ Skip error documentation
- ❌ Use inconsistent terminology
When to Use
Use this skill when:
- Writing function/method documentation
- Creating README files
- Documenting architecture decisions
- Writing code comments
- Generating API documentation
- Onboarding new team members