coding-principles

Code Quality Principles

Context

• Writing maintainable, readable code is a priority over clever optimizations
• Step-by-step implementation reduces errors and improves code quality
• Proper documentation and comments enhance long-term maintainability
• Following established coding standards improves collaboration
• The Unix philosophy of "do one thing well" leads to more robust solutions

Critical rules

• Proceed with small, focused steps instead of large, complex changes
• Always prioritize code readability and clarity over premature optimization
• Add explanatory comments to any complex or non-obvious logic
• Document all exported methods, functions, classes, and constants with purpose and usage notes
• Follow the established coding standards and conventions specific to the language in use
• Prefer simple, straightforward solutions over complex implementations
• Design components to do one thing well rather than multiple responsibilities
• Use descriptive variable and function names that reveal intent
• Break complex operations into smaller, focused functions
• Keep functions short and focused on a single responsibility
• Avoid deep nesting of control structures when possible
• Use consistent formatting throughout the codebase
• Apply the appropriate error handling approach for the language
• Include tests for new functionality when applicable
• Refactor duplicated code into reusable functions

Examples

/**

• Authenticates a user with provided credentials
• @param {string} username - The user's username
• @param {string} password - The user's password
• @returns {Promise} - The authenticated user or throws an error */ export async function authenticateUser(username, password) { // Validate inputs if (!username || !password) { throw new Error('Username and password required'); }