T1nker-1220 Code Quality Standards
Comprehensive code quality standards focused on minimalism, clarity, and correctness.
Core Principles
1. Correctness First, Optimization Later
Always check: Is the code even working correctly?
If NO:
- Fix correctness first before anything else
- Don't optimize broken code
- Focus on making it work properly
If YES:
- Measure before you optimize anything
- Default stance: No premature optimization, period
- Only optimize when performance issues are proven
Example:
// ❌ WRONG: Optimizing before it works correctly
function calculateTotal(items: any[]) {
// Using fancy reduce for "performance" but has bug
return items.reduce((sum, item) => sum + item.price, 0);
// BUG: Doesn't handle null prices
}
// ✅ RIGHT: Make it work correctly first
function calculateTotal(items: Item[]): number {
let total = 0;
for (const item of items) {
if (item.price != null) {
total += item.price;
}
}
return total;
}
// Then measure if performance is actually an issue
// Only optimize if measurements show it's needed
Code Minimalism
Goal: Less code, same functionality
Principle: Every Line Must Justify Its Existence
Bad - Verbose:
function getUserName(user: User): string {
if (user !== null && user !== undefined) {
if (user.name !== null && user.name !== undefined) {
if (user.name.length > 0) {
return user.name;
} else {
return 'Anonymous';
}
} else {
return 'Anonymous';
}
} else {
return 'Anonymous';
}
}
Good - Minimal:
function getUserName(user: User | null): string {
return user?.name || 'Anonymous';
}
Remove Unnecessary Abstractions
Bad - Over-abstracted:
interface IUserNameGetter {
getName(): string;
}
class UserNameGetterFactory {
static create(user: User): IUserNameGetter {
return new UserNameGetter(user);
}
}
class UserNameGetter implements IUserNameGetter {
constructor(private user: User) {}
getName(): string {
return this.user.name;
}
}
// Usage
const getter = UserNameGetterFactory.create(user);
const name = getter.getName();
Good - Simple:
function getUserName(user: User): string {
return user.name;
}
// Usage
const name = getUserName(user);
Clean and Powerful Over Verbose and Complex
Bad:
function processUserData(userData: any) {
const processedData = {
id: userData.id,
name: userData.name,
email: userData.email
};
if (userData.profile) {
processedData.profile = {
bio: userData.profile.bio,
avatar: userData.profile.avatar
};
}
if (userData.settings) {
processedData.settings = {
theme: userData.settings.theme,
notifications: userData.settings.notifications
};
}
return processedData;
}
Good:
function processUserData({ id, name, email, profile, settings }: UserData): ProcessedUser {
return {
id,
name,
email,
...(profile && { profile: { bio: profile.bio, avatar: profile.avatar } }),
...(settings && { settings: { theme: settings.theme, notifications: settings.notifications } })
};
}
Exact Functionality Only, No Extra Features
Bad - Adding unused features "just in case":
interface UserService {
getUser(id: string): Promise<User>;
getAllUsers(): Promise<User[]>; // Not needed yet
searchUsers(query: string): Promise<User[]>; // Not needed yet
updateUser(id: string, data: Partial<User>): Promise<User>; // Not needed yet
deleteUser(id: string): Promise<void>; // Not needed yet
}
Good - Only what's needed now:
interface UserService {
getUser(id: string): Promise<User>;
}
// Add other methods only when actually needed
Code Comments
Comment Format: "//comment here..."
Use inline comment format:
// Good
// This function calculates the total price including tax
/* Bad - avoid block comments unless absolutely necessary */
/* This function calculates
the total price
including tax */
Comment Length: 1-3 Lines Max Per Block
Bad - Too long:
// This function is responsible for processing user authentication
// by first validating the credentials against the database, then
// checking if the user has the necessary permissions, after which
// it generates a JWT token with appropriate claims and expiration
// time, and finally it logs the authentication event for security
// auditing purposes before returning the token to the caller
function authenticate(credentials: Credentials): Promise<AuthResult> {
// ...
}
Good - Concise:
// Validates credentials, generates JWT token, and logs auth event
function authenticate(credentials: Credentials): Promise<AuthResult> {
// ...
}
Explain Purpose and Functionality Clearly
Bad - Vague:
// Process data
function processData(data: unknown) { }
// Check stuff
if (user.age > 18) { }
Good - Clear:
// Validates and transforms user input into database format
function processData(data: unknown): DatabaseRecord { }
// Verify user is adult for age-restricted content
if (user.age > 18) { }
Professional and Standard Style
Bad - Informal:
// lol this is a hack but it works
// TODO: fix this mess later maybe???
// idk why this is needed but don't remove it!!!
Good - Professional:
// Temporary workaround for API v1 compatibility
// TODO: Remove after migrating to API v2 (PROJ-123)
// Required for backwards compatibility with legacy clients
Avoid Super Short Comments That Don't Explain Anything
Bad - Useless:
// Get user
const user = await getUser(id);
// Set name
user.name = newName;
// Save
await saveUser(user);
Good - Meaningful:
// Fetch user from database to ensure latest data
const user = await getUser(id);
// Update display name (validates against profanity filter)
user.name = sanitizeName(newName);
// Persist changes and trigger name change notifications
await saveUser(user);
Make Code Easy to Understand Through Meaningful Comments
Example:
// Calculate daily usage limit reset time
// Users get fresh credits at midnight UTC
const resetTime = new Date();
resetTime.setUTCHours(24, 0, 0, 0);
// Check if user exceeded their daily API quota
// Free tier: 100 requests, Pro tier: 1000 requests
const isOverQuota = user.dailyRequests >= getTierLimit(user.tier);
// Apply exponential backoff to prevent rapid retry storms
// Formula: baseDelay * (2 ^ retryCount) with max 60s
const backoffDelay = Math.min(
BASE_RETRY_DELAY * Math.pow(2, retryCount),
MAX_RETRY_DELAY
);
Code Quality Checklist
Before committing any code:
Correctness
- Code works correctly for all expected inputs
- Edge cases are handled
- Error handling is comprehensive
- No bugs or logical errors
Minimalism
- No unnecessary lines or abstractions
- Every line justifies its existence
- No "just in case" code
- No premature optimization
- No unused variables or functions
- No duplicate code
Comments
- Comments use "//comment" format
- Each comment block is 1-3 lines max
- Comments explain purpose and functionality
- Professional and standard style
- No vague or useless comments
- Complex logic is well-documented
Clarity
- Code is self-documenting where possible
- Variable names are descriptive
- Function names describe what they do
- Logic is easy to follow
- No clever tricks that sacrifice readability
Common Patterns
Simplify Conditional Logic
Bad:
function canAccessFeature(user: User): boolean {
if (user.isPremium === true) {
return true;
} else {
if (user.trialActive === true) {
return true;
} else {
return false;
}
}
}
Good:
function canAccessFeature(user: User): boolean {
return user.isPremium || user.trialActive;
}
Reduce Nesting
Bad:
function processOrder(order: Order) {
if (order.isValid) {
if (order.isPaid) {
if (order.items.length > 0) {
// Process order
return processItems(order.items);
}
}
}
return null;
}
Good:
function processOrder(order: Order) {
// Early returns reduce nesting
if (!order.isValid) return null;
if (!order.isPaid) return null;
if (order.items.length === 0) return null;
// Main logic at top level
return processItems(order.items);
}
Extract Complex Conditions
Bad:
if (user.age >= 18 && user.hasVerifiedEmail && !user.isBanned && user.acceptedTerms) {
// Allow access
}
Good:
// Extract to named function that explains intent
function canAccessAdultContent(user: User): boolean {
return (
user.age >= 18 &&
user.hasVerifiedEmail &&
!user.isBanned &&
user.acceptedTerms
);
}
if (canAccessAdultContent(user)) {
// Allow access
}
Avoid Premature Optimization
Bad:
// "Optimizing" by caching before knowing if it's needed
const cache = new Map<string, User>();
function getUser(id: string): User {
if (cache.has(id)) {
return cache.get(id)!;
}
const user = fetchUser(id);
cache.set(id, user);
return user;
}
Good:
// Simple and correct first
function getUser(id: string): User {
return fetchUser(id);
}
// Add caching ONLY if measurements show it's needed
// And only after proving correctness
Remove Dead Code
Bad:
function calculatePrice(item: Item): number {
// Old calculation
// const basePrice = item.price * 1.1;
// const tax = basePrice * 0.08;
// return basePrice + tax;
// New calculation
return item.price * 1.18;
// Keeping old code "just in case"
}
Good:
function calculatePrice(item: Item): number {
// Price includes 18% markup (10% margin + 8% tax)
return item.price * 1.18;
}
// Old code deleted - version control keeps history if needed
Anti-Patterns to Avoid
Don't Write "Clever" Code
Bad:
// Too clever - hard to understand
const result = arr.reduce((a, b) => a.concat(b.map(c => c.split(',').filter(d => d))), []);
Good:
// Clear and readable
const result: string[] = [];
for (const item of arr) {
for (const value of item) {
const parts = value.split(',').filter(part => part.trim());
result.push(...parts);
}
}
Don't Add Unnecessary Layers
Bad:
class UserRepository {
async getUser(id: string): Promise<User> {
return this.database.users.findById(id);
}
}
class UserService {
constructor(private repo: UserRepository) {}
async getUser(id: string): Promise<User> {
return this.repo.getUser(id);
}
}
class UserController {
constructor(private service: UserService) {}
async getUser(id: string): Promise<User> {
return this.service.getUser(id);
}
}
Good:
// Only add layers when they provide actual value
async function getUser(id: string): Promise<User> {
return database.users.findById(id);
}
// Add service layer only when business logic is needed
Don't Optimize Before Measuring
Bad:
// Micro-optimizing without measurements
const result = [];
const len = arr.length; // "Faster" to cache length
for (let i = 0; i < len; ++i) { // Using ++i "for performance"
result.push(arr[i]);
}
Good:
// Clear code first, optimize only if proven needed
const result = [];
for (const item of arr) {
result.push(item);
}
// Or even simpler
const result = [...arr];
Summary: Quality Over Quantity
Core Values:
- Correctness First - Make it work right before making it fast
- Minimalism - Less code, same functionality
- Clarity - Clean and powerful over verbose and complex
- Meaningful Comments - Explain why and how, not what
- No Premature Optimization - Measure before optimizing
- Every Line Counts - Each line must justify its existence
Remember: The best code is code that doesn't need to exist. The second best is code that's simple, correct, and easy to understand.