pixelastic/code-writer

Code Writer

Overview

Code should communicate intent clearly. Excessive comments and output statements create noise that obscures logic.

Core principle: Minimize noise, maximize signal. Comments explain why, not what. Output statements serve a purpose, not narration.

Language-Specific Skills

These guidelines apply to all programming languages. For language-specific patterns and conventions, use the appropriate language-specific skill:

• JavaScript: Use js-writer skill for JavaScript/Node.js code
• ZSH: Use zsh-writer skill for ZSH functions in .oroshi repository

Language-specific skills extend these core guidelines with syntax and idioms specific to that language.

When to Use

• Writing new functions or methods
• Modifying existing code
• Adding features or fixing bugs
• Refactoring code

When NOT to use:

• Generated code (linters handle style)
• Configuration files (different conventions)

Output Statements

Output statements include: console.log(), print(), echo, printf(), puts, System.out.println(), etc.

Default: ZERO output statements

Allowed ONLY for:

1. Display functions - Functions whose purpose IS to output data
2. Error messages to stderr - Usage errors with clear error indication

FORBIDDEN:

• Progress messages ("Processing...", "Starting...", "Done")
• Status summaries ("Found X items", "Total: Y")
• Empty lines (console.log(""))
• Decorative headers ("===== Summary =====")
• Debug traces ("checkpoint 1", "here")

Examples

// ✅ Display function - output IS the purpose
function listBranches(branches) {
  branches.forEach(b => console.log(b.name));
}

// ✅ Error to stderr
if (!filePath) {
  console.error("Error: File path required");
  return null;
}

// ❌ FORBIDDEN - Progress narration
console.log("Starting analysis...");
const results = compute(data);
console.log(`Found ${results.length} items`);

If unsure whether to add output: DON'T.

Comments

Default: Function documentation ONLY

Allowed:

1. Function documentation - What it does, parameters, return value
2. Section comments - ONE comment for 3+ grouped operations
3. Data meaning - What data represents (not what code does)

FORBIDDEN:

• Explaining what code does (code should be self-explanatory)
• One comment per operation/line
• Loop comments (// Process each item)
• Format conversions (// color1 #ef4444 when RGB already in code)
• Source metadata that isn't actionable (// from palette index 5)
• Breadcrumbs from debugging process
• Obvious section headers (// Additional colors)

Examples

// ✅ Explains semantic meaning
#define BLACK ((Color){0, 0, 0})  // Off/disabled

// ❌ FORBIDDEN - Redundant format conversion
#define RED ((Color){239, 68, 68})  // #ef4444

// ❌ FORBIDDEN - Per-line metadata
#define PURPLE ((Color){128, 90, 213})  // color5 from kitty

// ❌ FORBIDDEN - Obvious section header
// Additional color definitions
#define CYAN ((Color){8, 145, 178})

// ✅ Function documentation
/**
 * Retry operation up to maxAttempts times
 * @param {Function} operation - Async function to retry
 * @returns {Promise} Result of operation
 */
async function retryOperation(operation, maxAttempts) {
  // ...
}

// ✅ ONE section comment for 3+ validations
// Validate required config fields
if (!config.apiKey) throw new Error("Missing apiKey");
if (!config.endpoint) throw new Error("Missing endpoint");
if (!config.timeout) throw new Error("Missing timeout");

// ✅ Data meaning
// First line contains headers
if (lineNumber === 0) {
  return parseHeaders(line);
}

// ❌ FORBIDDEN - Explains what code does
// Check if file exists
if (!fs.existsSync(filePath)) {
  return null;
}

// ❌ FORBIDDEN - Loop comment
// Loop through users
for (const user of users) {
  processUser(user);
}

When editing existing code: Never remove existing comments.

If unsure whether to add comment: DON'T.

Quick Reference

| Category | Default | Allowed | Forbidden | |----------|---------|---------|-----------| | Output | Zero | Display functions, errors to stderr | Progress, status, decorative headers | | Comments | Function docs only | Section (3+ ops), data meaning | What code does, per-line, format conversions |

Common Mistakes

| Mistake | Why Wrong | Fix | |---------|-----------|-----| | Per-line comments | Visual noise, obvious from code | Remove, use descriptive names | | Format conversion comments | Redundant data in different format | Remove, keep one format | | Progress messages | Narrates obvious execution | Remove or use logging framework | | Section headers stating obvious | Spatial grouping already clear | Remove | | Breadcrumb comments | Documents debugging journey | Remove after fixing |

Real-World Impact

Before:

// Additional colors from kitty palette
#define RED     ((Color){239, 68, 68})    // color1 #ef4444
#define PURPLE  ((Color){128, 90, 213})   // color5 #805ad5
#define CYAN    ((Color){8, 145, 178})    // color6 #0891b2

After:

#define RED     ((Color){239, 68, 68})
#define PURPLE  ((Color){128, 90, 213})
#define CYAN    ((Color){8, 145, 178})

Clean code: 60% less noise, same information, better readability.