code-writer

name	code-writer
description	Use when writing or modifying code in any programming language. Apply when adding functions, fixing bugs, or implementing features.

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.