thesimonho-coding-standards
SKILL.md
Coding Standards & Best Practices
Universal coding standards applicable across all projects.
Code Quality Principles
1. Readability First
- Code is read more than written
- Clear variable and function names
- Self-documenting code preferred over comments
- Consistent formatting
2. KISS (Keep It Simple, Stupid)
- Simplest solution that works
- Avoid over-engineering
- No premature optimization
- Easy to understand > clever code
3. DRY (Don't Repeat Yourself)
- Extract common logic into functions
- Create reusable components
- Share utilities across modules
- Avoid copy-paste programming
4. YAGNI (You Aren't Gonna Need It)
- Don't build features before they're needed
- Avoid speculative generality
- Add complexity only when required
- Start simple, refactor when needed
TypeScript/JavaScript Standards
Variable Naming
// ✅ GOOD: Descriptive names
const marketSearchQuery = "election";
const isUserAuthenticated = true;
const totalRevenue = 1000;
// ❌ BAD: Unclear names
const q = "election";
const flag = true;
const x = 1000;
Function Naming
// ✅ GOOD: Verb-noun pattern
async function fetchMarketData(marketId: string) {}
function calculateSimilarity(a: number[], b: number[]) {}
function isValidEmail(email: string): boolean {}
// ❌ BAD: Unclear or noun-only
async function market(id: string) {}
function similarity(a, b) {}
function email(e) {}
Immutability Pattern
ALWAYS create new objects, NEVER mutate:
// ✅ ALWAYS use spread operator
const updatedUser = {
...user,
name: "New Name",
};
const updatedArray = [...items, newItem];
// ❌ NEVER mutate directly
user.name = "New Name"; // BAD
items.push(newItem); // BAD
Error Handling
Write defensive code with guards and type narrowing.
ALWAYS handle errors comprehensively:
// ✅ GOOD: Comprehensive error handling
async function fetchData(url: string) {
try {
const response = await fetch(url);
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}
return await response.json();
} catch (error) {
console.error("Fetch failed:", error);
throw new Error("Failed to fetch data");
}
}
// ❌ BAD: No error handling
async function fetchData(url) {
const response = await fetch(url);
return response.json();
}
Async/Await Best Practices
// ✅ GOOD: Parallel execution when possible
const [users, markets, stats] = await Promise.all([
fetchUsers(),
fetchMarkets(),
fetchStats(),
]);
// ❌ BAD: Sequential when unnecessary
const users = await fetchUsers();
const markets = await fetchMarkets();
const stats = await fetchStats();
Type Safety
// ✅ GOOD: Proper types
interface Market {
id: string;
name: string;
status: "active" | "resolved" | "closed";
created_at: Date;
}
function getMarket(id: string): Promise<Market> {
// Implementation
}
// ❌ BAD: Using 'any'
function getMarket(id: any): Promise<any> {
// Implementation
}
React Best Practices
Component Structure
// ✅ GOOD: Functional component with types
interface ButtonProps {
children: React.ReactNode
onClick: () => void
disabled?: boolean
variant?: 'primary' | 'secondary'
}
export function Button({
children,
onClick,
disabled = false,
variant = 'primary'
}: ButtonProps) {
return (
<button
onClick={onClick}
disabled={disabled}
className={`btn btn-${variant}`}
>
{children}
</button>
)
}
// ❌ BAD: No types, unclear structure
export function Button(props) {
return <button onClick={props.onClick}>{props.children}</button>
}
Custom Hooks
// ✅ GOOD: Reusable custom hook
export function useDebounce<T>(value: T, delay: number): T {
const [debouncedValue, setDebouncedValue] = useState<T>(value);
useEffect(() => {
const handler = setTimeout(() => {
setDebouncedValue(value);
}, delay);
return () => clearTimeout(handler);
}, [value, delay]);
return debouncedValue;
}
// Usage
const debouncedQuery = useDebounce(searchQuery, 500);
State Management
// ✅ GOOD: Proper state updates
const [count, setCount] = useState(0);
// Functional update for state based on previous state
setCount((prev) => prev + 1);
// ❌ BAD: Direct state reference
setCount(count + 1); // Can be stale in async scenarios
Conditional Rendering
// ✅ GOOD: Clear conditional rendering
{isLoading && <Spinner />}
{error && <ErrorMessage error={error} />}
{data && <DataDisplay data={data} />}
// ❌ BAD: Ternary hell
{isLoading ? <Spinner /> : error ? <ErrorMessage error={error} /> : data ? <DataDisplay data={data} /> : null}
API Design Standards
REST API Conventions
GET /api/markets # List all markets
GET /api/markets/:id # Get specific market
POST /api/markets # Create new market
PUT /api/markets/:id # Update market (full)
PATCH /api/markets/:id # Update market (partial)
DELETE /api/markets/:id # Delete market
# Query parameters for filtering
GET /api/markets?status=active&limit=10&offset=0
Response Format
// ✅ GOOD: Consistent response structure
interface ApiResponse<T> {
success: boolean;
data?: T;
error?: string;
meta?: {
total?: number;
page?: number;
limit?: number;
};
}
// Success response
return NextResponse.json({
success: true,
data: markets,
meta: { total: 100, page: 1, limit: 10 },
});
// Error response
return NextResponse.json(
{
success: false,
error: "Invalid request",
},
{ status: 400 },
);
Input Validation
ALWAYS validate user input:
import { z } from "zod";
// ✅ GOOD: Schema validation
const CreateMarketSchema = z.object({
name: z.string().min(1).max(200),
description: z.string().min(1).max(2000),
endDate: z.string().datetime(),
categories: z.array(z.string()).min(1),
});
export async function POST(request: Request) {
const body = await request.json();
try {
const validated = CreateMarketSchema.parse(body);
// Proceed with validated data
} catch (error) {
if (error instanceof z.ZodError) {
return NextResponse.json(
{
success: false,
error: "Validation failed",
details: error.errors,
},
{ status: 400 },
);
}
}
}
Comments & Documentation
When to Comment
// ✅ GOOD: Explain WHY, not WHAT
// Use exponential backoff to avoid overwhelming the API during outages
const delay = Math.min(1000 * Math.pow(2, retryCount), 30000);
// Deliberately using mutation here for performance with large arrays
items.push(newItem);
// ❌ BAD: Stating the obvious
// Increment counter by 1
count++;
// Set name to user's name
name = user.name;
Testing Standards
Test Structure (AAA Pattern)
test("calculates similarity correctly", () => {
// Arrange
const vector1 = [1, 0, 0];
const vector2 = [0, 1, 0];
// Act
const similarity = calculateCosineSimilarity(vector1, vector2);
// Assert
expect(similarity).toBe(0);
});
Test Naming
// ✅ GOOD: Descriptive test names
test("returns empty array when no markets match query", () => {});
test("throws error when OpenAI API key is missing", () => {});
test("falls back to substring search when Redis unavailable", () => {});
// ❌ BAD: Vague test names
test("works", () => {});
test("test search", () => {});
Code Smell Detection
Watch for these anti-patterns:
1. Long Functions
// ❌ BAD: Function > 50 lines
function processMarketData() {
// 100 lines of code
}
// ✅ GOOD: Split into smaller functions
function processMarketData() {
const validated = validateData();
const transformed = transformData(validated);
return saveData(transformed);
}
2. Deep Nesting
// ❌ BAD: 5+ levels of nesting
if (user) {
if (user.isAdmin) {
if (market) {
if (market.isActive) {
if (hasPermission) {
// Do something
}
}
}
}
}
// ✅ GOOD: Early returns
if (!user) return;
if (!user.isAdmin) return;
if (!market) return;
if (!market.isActive) return;
if (!hasPermission) return;
// Do something
3. Magic Numbers
// ❌ BAD: Unexplained numbers
if (retryCount > 3) {
}
setTimeout(callback, 500);
// ✅ GOOD: Named constants
const MAX_RETRIES = 3;
const DEBOUNCE_DELAY_MS = 500;
if (retryCount > MAX_RETRIES) {
}
setTimeout(callback, DEBOUNCE_DELAY_MS);
Remember: Code quality is not negotiable. Clear, maintainable code enables rapid development and confident refactoring.