coding-standards
Comprehensive coding standards and best practices for maintainable, consistent software development across multiple languages and paradigms
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for implementing coding standards and best practices across various programming languages. It focuses on enhancing code maintainability, readability, and consistency through proven architectural principles like SOLID, DRY, and automated quality enforcement, helping teams reduce technical debt and improve project scalability.
Use Cases
- Standardizing Codebases: Establishing unified style guides and naming conventions for multi-language development teams to ensure consistency.
- Architectural Refactoring: Applying SOLID principles and design patterns to transform complex legacy systems into modular, testable architectures.
- Automated Quality Workflows: Configuring linters, formatters, and pre-commit hooks to enforce high-quality code standards automatically within CI/CD pipelines.
- Technical Documentation: Implementing standardized documentation patterns (like JSDoc or Sphinx) to improve code discoverability and developer onboarding.
- Performance & Concurrency: Utilizing advanced patterns such as memoization and parallel execution to optimize application performance and resource management.
| name | coding-standards |
|---|---|
| description | Comprehensive coding standards and best practices for maintainable, consistent software development across multiple languages and paradigms |
Coding Standards Skill
Level 1: Quick Start (5 minutes)
What You'll Learn
Apply essential coding standards for clean, maintainable code that follows industry best practices.
Core Principles
- Consistency: Follow established style guides (PEP 8, Airbnb, Google)
- Readability: Write self-documenting code with clear naming
- Maintainability: Keep functions small (<50 lines), files focused (<500 lines)
- Quality: Enforce standards with linters and formatters
Quick Reference
# ✅ Good: Clear naming, single responsibility
def calculate_user_discount(user: User, order: Order) -> Decimal:
"""Calculate discount based on user tier and order total."""
if user.tier == "premium":
return order.total * Decimal("0.15")
return order.total * Decimal("0.05")
# ❌ Bad: Unclear naming, mixed concerns
def calc(u, o):
d = 0.15 if u.t == "p" else 0.05
save_to_db(u, o, d) # Side effect!
return o.t * d
Essential Checklist
- Follow language-specific style guide
- Use meaningful, descriptive names
- Limit function complexity (cyclomatic < 10)
- Configure linter and formatter
- Add pre-commit hooks
Common Pitfalls
- Inconsistent naming conventions within a project
- Functions that do too many things
- Missing or outdated documentation
- Skipping code reviews
Level 2: Implementation (30 minutes)
Deep Dive Topics
1. Code Style and Formatting
Naming Conventions by Language:
// TypeScript/JavaScript
class UserService {} // PascalCase for classes
const getUserById = () => {} // camelCase for functions
const API_ENDPOINT = "..." // UPPER_SNAKE_CASE for constants
# Python
class UserService: # PascalCase for classes
def get_user_by_id(): # snake_case for functions
API_ENDPOINT = "..." # UPPER_SNAKE_CASE for constants
File Organization:
src/
├── models/ # Data models and types
├── services/ # Business logic (max 500 lines/file)
├── controllers/ # Request handlers
├── utils/ # Shared utilities
└── config/ # Configuration
2. Documentation Standards
Function Documentation:
/**
* Calculates the final price after applying discounts and tax.
*
* @param basePrice - The original price before any adjustments
* @param discountRate - Discount as a decimal (0.1 = 10%)
* @param taxRate - Tax rate as a decimal (0.08 = 8%)
* @returns The final price rounded to 2 decimal places
* @throws {ValidationError} If basePrice is negative
*
* @example
* const finalPrice = calculateFinalPrice(100, 0.1, 0.08);
* // Returns 97.20 (100 - 10% discount + 8% tax)
*/
function calculateFinalPrice(
basePrice: number,
discountRate: number,
taxRate: number
): number {
if (basePrice < 0) {
throw new ValidationError("Base price cannot be negative");
}
const discounted = basePrice * (1 - discountRate);
return Math.round(discounted * (1 + taxRate) * 100) / 100;
}
3. Architecture Patterns
SOLID Principles Application:
// Single Responsibility Principle
class UserRepository {
async findById(id: string): Promise<User> {}
async save(user: User): Promise<void> {}
}
class UserValidator {
validate(user: User): ValidationResult {}
}
// Dependency Injection
class UserService {
constructor(
private readonly repository: UserRepository,
private readonly validator: UserValidator
) {}
async createUser(userData: UserData): Promise<User> {
const validation = this.validator.validate(userData);
if (!validation.isValid) {
throw new ValidationError(validation.errors);
}
return this.repository.save(new User(userData));
}
}
4. Error Handling
// Custom error hierarchy
class ApplicationError extends Error {
constructor(
message: string,
public code: string,
public statusCode: number = 500
) {
super(message);
this.name = this.constructor.name;
}
}
class ValidationError extends ApplicationError {
constructor(message: string, public fields: string[]) {
super(message, "VALIDATION_ERROR", 400);
}
}
// Usage with proper error handling
async function processPayment(payment: Payment): Promise<Result> {
try {
validatePaymentData(payment);
const result = await paymentGateway.charge(payment);
await auditLog.record("payment.success", { paymentId: result.id });
return result;
} catch (error) {
if (error instanceof ValidationError) {
logger.warn("Invalid payment data", { fields: error.fields });
throw error;
}
logger.error("Payment processing failed", { error, payment });
throw new ApplicationError(
"Payment processing failed",
"PAYMENT_ERROR",
502
);
}
}
Implementation Patterns
DRY (Don't Repeat Yourself)
// ❌ Bad: Repeated logic
function calculateEmployeeSalary(employee: Employee): number {
if (employee.type === "full-time") {
return employee.baseSalary * 1.2 + 5000;
}
return employee.baseSalary * 1.2;
}
function calculateContractorPay(contractor: Contractor): number {
return contractor.baseSalary * 1.2;
}
// ✅ Good: Extracted common logic
function applyStandardBonus(baseSalary: number): number {
return baseSalary * 1.2;
}
function calculateEmployeeSalary(employee: Employee): number {
const withBonus = applyStandardBonus(employee.baseSalary);
return employee.type === "full-time" ? withBonus + 5000 : withBonus;
}
Automation Tools
// package.json - Automation setup
{
"scripts": {
"lint": "eslint . --ext .ts,.tsx",
"format": "prettier --write \"**/*.{ts,tsx,json,md}\"",
"type-check": "tsc --noEmit",
"validate": "npm run lint && npm run type-check && npm run test"
},
"husky": {
"hooks": {
"pre-commit": "lint-staged"
}
},
"lint-staged": {
"*.{ts,tsx}": ["eslint --fix", "prettier --write"],
"*.{json,md}": ["prettier --write"]
}
}
Integration Points
- Links to Security Standards for secure coding
- Links to Testing Standards for testable code design
- Links to NIST Compliance for SI-10, SI-11 controls
Level 3: Mastery (Extended Learning)
Advanced Topics
1. Performance Optimization Patterns
Memoization:
function memoize<T extends (...args: any[]) => any>(fn: T): T {
const cache = new Map<string, ReturnType<T>>();
return ((...args: Parameters<T>) => {
const key = JSON.stringify(args);
if (cache.has(key)) {
return cache.get(key);
}
const result = fn(...args);
cache.set(key, result);
return result;
}) as T;
}
// Usage
const expensiveCalculation = memoize((n: number) => {
// Complex computation
return Array.from({ length: n }, (_, i) => i * i).reduce((a, b) => a + b);
});
2. Concurrency Patterns
// Parallel execution with error handling
async function processItemsConcurrently<T, R>(
items: T[],
processor: (item: T) => Promise<R>,
concurrency: number = 5
): Promise<Array<R | Error>> {
const results: Array<R | Error> = [];
const executing: Promise<void>[] = [];
for (const item of items) {
const promise = processor(item)
.then((result) => {
results.push(result);
})
.catch((error) => {
results.push(error);
});
executing.push(promise);
if (executing.length >= concurrency) {
await Promise.race(executing);
executing.splice(
executing.findIndex((p) => p === promise),
1
);
}
}
await Promise.all(executing);
return results;
}
3. API Design Best Practices
// RESTful API design
interface ApiResponse<T> {
data: T;
meta: {
timestamp: string;
requestId: string;
};
errors?: ApiError[];
}
// Versioning strategy
app.use("/api/v1", v1Routes);
app.use("/api/v2", v2Routes);
// Pagination standard
interface PaginatedResponse<T> extends ApiResponse<T[]> {
pagination: {
page: number;
pageSize: number;
totalItems: number;
totalPages: number;
};
}
4. Refactoring Strategies
Extract Method:
// Before
function generateReport(data: Data[]): Report {
// 100+ lines of complex logic
const filtered = data.filter(/* complex condition */);
const transformed = filtered.map(/* complex transformation */);
const aggregated = transformed.reduce(/* complex aggregation */);
// More complex logic...
}
// After
function generateReport(data: Data[]): Report {
const filtered = filterRelevantData(data);
const transformed = transformDataForReport(filtered);
const aggregated = aggregateMetrics(transformed);
return formatReport(aggregated);
}
Resources
Essential Reading
- Clean Code by Robert C. Martin
- Refactoring by Martin Fowler
- Design Patterns: Elements of Reusable Object-Oriented Software
Tools and Frameworks
- Linters: ESLint, Pylint, RuboCop, Checkstyle
- Formatters: Prettier, Black, gofmt
- Static Analysis: SonarQube, CodeClimate, DeepSource
- Documentation: JSDoc, Sphinx, Doxygen
Language-Specific Style Guides
- Python PEP 8
- Google JavaScript Style Guide
- Airbnb JavaScript Style Guide
- Google Java Style Guide
- Effective Go
Templates
Code Review Checklist
## Code Review Checklist
### Functionality
- [ ] Code meets requirements
- [ ] Edge cases handled
- [ ] Error handling comprehensive
### Code Quality
- [ ] Follows style guide
- [ ] Names are clear and descriptive
- [ ] Functions are focused (<50 lines)
- [ ] No code duplication
### Testing
- [ ] Unit tests included
- [ ] Tests cover edge cases
- [ ] Tests are maintainable
### Documentation
- [ ] Public APIs documented
- [ ] Complex logic explained
- [ ] README updated if needed
### Security
- [ ] No hardcoded secrets
- [ ] Input validation present
- [ ] SQL injection prevented
Scripts
Complexity Checker
#!/usr/bin/env python3
"""Check cyclomatic complexity of Python files."""
import sys
from radon.complexity import cc_visit
def check_complexity(filename: str, max_complexity: int = 10) -> bool:
"""Check if file exceeds complexity threshold."""
with open(filename) as f:
code = f.read()
results = cc_visit(code)
violations = [r for r in results if r.complexity > max_complexity]
if violations:
print(f"❌ {filename}: Complexity violations found")
for v in violations:
print(f" - {v.name}: complexity {v.complexity} (max {max_complexity})")
return False
print(f"✅ {filename}: All functions within complexity limit")
return True
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Usage: check_complexity.py <file>")
sys.exit(1)
passed = check_complexity(sys.argv[1])
sys.exit(0 if passed else 1)
Examples
Basic Usage
// TODO: Add basic example for coding-standards
// This example demonstrates core functionality
Advanced Usage
// TODO: Add advanced example for coding-standards
// This example shows production-ready patterns
Integration Example
// TODO: Add integration example showing how coding-standards
// works with other systems and services
See examples/coding-standards/ for complete working examples.
Integration Points
This skill integrates with:
Upstream Dependencies
- Tools: Common development tools and frameworks
- Prerequisites: Basic understanding of general concepts
Downstream Consumers
- Applications: Production systems requiring coding-standards functionality
- CI/CD Pipelines: Automated testing and deployment workflows
- Monitoring Systems: Observability and logging platforms
Related Skills
- See other skills in this category
Common Integration Patterns
- Development Workflow: How this skill fits into daily development
- Production Deployment: Integration with production systems
- Monitoring & Alerting: Observability integration points
Common Pitfalls
Pitfall 1: Insufficient Testing
Problem: Not testing edge cases and error conditions leads to production bugs
Solution: Implement comprehensive test coverage including:
- Happy path scenarios
- Error handling and edge cases
- Integration points with external systems
Prevention: Enforce minimum code coverage (80%+) in CI/CD pipeline
Pitfall 2: Hardcoded Configuration
Problem: Hardcoding values makes applications inflexible and environment-dependent
Solution: Use environment variables and configuration management:
- Separate config from code
- Use environment-specific configuration files
- Never commit secrets to version control
Prevention: Use tools like dotenv, config validators, and secret scanners
Pitfall 3: Ignoring Security Best Practices
Problem: Security vulnerabilities from not following established security patterns
Solution: Follow security guidelines:
- Input validation and sanitization
- Proper authentication and authorization
- Encrypted data transmission (TLS/SSL)
- Regular security audits and updates
Prevention: Use security linters, SAST tools, and regular dependency updates
Best Practices:
- Follow established patterns and conventions for coding-standards
- Keep dependencies up to date and scan for vulnerabilities
- Write comprehensive documentation and inline comments
- Use linting and formatting tools consistently
- Implement proper error handling and logging
- Regular code reviews and pair programming
- Monitor production metrics and set up alerts
Bundled Resources
- Full CODING_STANDARDS.md
- UNIFIED_STANDARDS.md
- Example linter configs in
./resources/ - Pre-commit hook templates in
./templates/ - Complexity checking scripts in
./scripts/