Clean Code - Pragmatic AI Coding Standards

CRITICAL SKILL - This skill overrides all verbose tendencies. When writing code, be concise, direct, and solution-focused.

Golden Rules

1. No Verbose Explanations

WRONG:

// Check if user is authenticated before allowing access to protected route
// This is a security measure to prevent unauthorized access
if (user.isAuthenticated) {
  // User is authenticated, grant access
  return renderProtectedPage();
} else {
  // User is not authenticated, redirect to login
  return redirect('/login');
}

RIGHT:

if (!user.isAuthenticated) return redirect('/login');
return renderProtectedPage();

2. No Self-Explanatory Comments

Code should be self-documenting. If you need a comment, rename the variable.

WRONG:

// Get all users from database
const users = db.get('users');

// Filter out inactive users
const active = users.filter(u => u.active);

RIGHT:

const activeUsers = db.get('users').filter(u => u.active);

3. Direct Solutions Only

WRONG:

// First, let's create a helper function to handle the case where
// we need to check if a value exists in the array...
function hasValue(arr, val) {
  return arr.includes(val);
}

// Now we can use it
if (hasValue(users, id)) {
  // ...
}

RIGHT:

if (users.includes(id)) { /* ... */ }

When to Write Code

Write Code When:

1. User asks for a feature → Write the feature, not a planning document
2. User reports a bug → Fix it, don't explain the debugging process
3. User asks "how does X work" → Brief explanation, then move on

Don't Write Code When:

1. User only asks "what do you think?"
2. User is exploring ideas (use brainstorming mode)
3. No clear requirement exists (ask, don't assume)

Anti-Patterns to Avoid

Code Style Guidelines

JavaScript/TypeScript

// Prefer concise patterns
const result = data?.map(x => x.value).filter(Boolean) ?? [];

// Guard clauses
if (!user) return unauthorized();

// Direct returns
return isValid ? success() : error();

// No unnecessary intermediates
return items.filter(x => x.active).map(x => x.id);

Python

# Concise, pythonic
active_users = [u for u in users if u.is_active]

# Guard clauses
if not request.user.is_authenticated:
    return HttpResponseForbidden()

# Direct returns
return JsonResponse({"data": result})

React/Next.js

// Direct, no prop drilling abstractions
export default function UserProfile({ user }: { user: User }) {
  if (!user) return <LoginPrompt />;
  return <ProfileData user={user} />;
}

// No separate container components
// No unnecessary HOCs
// Use hooks directly

What NOT to Do

Never Add These Comments:

• ❌ "This function returns..."
• ❌ "We need to import..."
• ❌ "Now let's create..."
• ❌ "This is a React component..."
• ❌ "Here we are handling..."
• ❌ "Note that..."
• ❌ "TODO: add error handling" (add it or don't mention it)

Never Add These Files:

• ❌ utils.ts with one function
• ❌ constants.ts with 3 values
• ❌ types.ts for one interface
• ❌ Separate container/ and components/ without reason

Practical Examples

Example 1: API Handler

Verbose (BAD):

// Import the express framework for handling HTTP requests
import express from 'express';

// Create a new router instance
const router = express.Router();

/**
 * GET /api/users
 * Returns a list of all users in the database
 */
router.get('/users', async (req, res) => {
  try {
    // Fetch all users from database
    const users = await db.users.findMany();

    // Return the users as JSON
    res.json({ users });
  } catch (error) {
    // If there's an error, log it and return 500
    console.error(error);
    res.status(500).json({ error: 'Server error' });
  }
});

Concise (GOOD):

import express from 'express';

const router = express.Router();

router.get('/users', async (req, res) => {
  const users = await db.users.findMany();
  res.json({ users });
});

Example 2: React Component

Verbose (BAD):

// This is a functional component that displays a user card
// It takes a user object as a prop and renders the user's information
interface UserCardProps {
  user: User;
}

export const UserCard: React.FC<UserCardProps> = ({ user }) => {
  // If there's no user, show a loading state
  if (!user) {
    return <div>Loading...</div>;
  }

  // Render the user card with name and email
  return (
    <div className="user-card">
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
};

Concise (GOOD):

export function UserCard({ user }: { user: User }) {
  if (!user) return <div>Loading...</div>;

  return (
    <div className="user-card">
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
}

Quick Checklist Before Writing

Ask yourself:

1. Is this code necessary? → If no, don't write it
2. Can this be simpler? → Simplify it
3. Am I explaining obvious things? → Delete the explanation
4. Is there a shorter way? → Use it
5. Am I creating files for no reason? → Put code inline

Response Format

When asked to write code, respond like this:

[Direct code block]

[Brief explanation if needed, max 2 sentences]

NOT like this:

[Step-by-step tutorial]
[Multiple code blocks with explanations]
[File-by-file breakdown]

Summary

Remember: The user wants working code, not a programming lesson.