AI Skill Report Card
Humanizing Code
YAML--- name: humanizing-code description: Writes and edits code so it reads like an experienced human wrote it, not an AI assistant. Use when the user asks to humanize, de-AI, or clean up code, or anytime code is being written/edited and should avoid AI tells like excessive comments, docstring bloat, section banners, generic names, and over-engineered structure. ---
Humanizing Code
Core Rule
Write the code a good senior developer would leave in review: direct, idiomatic, quiet. Comments are the exception, not the default. When in doubt, write no comment.
Quick Start14 / 15
Before touching code:
- Open two or three neighbouring files. Match their comment density, docstring style, naming, and formatting.
- Note the public API, serialized keys, and config names — these don't get renamed.
- Write the simplest direct version. No speculative abstraction, no unrequested helpers.
- Delete every comment that restates the line below it, and every separator banner.
- Run the repo's formatter, linter, and tests.
Recommendation▾
Add an example showing naming conventions improvement (generic var -> domain-specific) as a standalone before/after pair, not just the inline helper case
The Comment Law
Default budget: zero comments, zero docstrings.
Add a comment only when it explains something the code cannot show:
- a non-obvious why
- a constraint or invariant
- a workaround with a reason
- a unit or side effect that would surprise someone
If added, it's one short line, using the language's plain single-line comment syntax (// in JS/TS/C/Java/Go/Rust, # in Python/Ruby/Shell). Never a block comment, never a decorated one.
Never write:
- docstrings with
Args:,Returns:,Raises:,Example:, or"""block comments used as inline notes - comments restating the next line ("Initialize...", "Loop over...", "Check if...", "Return...")
- "This function...", "Note that...", "Here we...", "Step 1:", section banners
- separator lines of any kind — no
// ----------------,# ====,/* *** */,///////, box-drawing, or ASCII art, ever, under any length - TODO or placeholder comments
- emoji or chatty remarks
Docstrings only if the repo already uses them on comparable functions, or the user asks — then one sentence, no parameter list. If the user says "no comments," write none, even on public functions.
Workflow14 / 15
Progress:
- Survey 2-3 neighbouring files for conventions
- Identify public API / serialized keys / config names to preserve
- Write the simplest direct implementation
- Name variables by domain role, not generic placeholders
- Strip every comment that restates code, and every divider/banner line
- Match repo's formatting/typing style, don't over-format
- Run formatter, linter, tests
- Re-read diff for scope creep, leftover comments, and stray separator lines
Recommendation▾
Include a brief example of appropriate comment usage (the rare case where a one-liner explaining 'why' is warranted) to balance the otherwise comment-negative framing
Editing Existing Code
- Freeze behavior first: tests, public API, serialized keys stay stable.
- Keep the diff small — don't reformat the whole file.
- Rename only locals whose role is unambiguous; skip unclear ones.
- To rewrite identifiers, use the parser/AST — never regex over source text (Python:
ast/libcst; JS/TS: Babel/recast; Java: JavaParser; C++: libclang). - Preserve existing comments unless wrong or redundant.
- Don't add comments just because you touched the line.
- If the file already has divider banners, don't add more, and remove them from any block you're editing anyway.
Examples17 / 20
Example 1:
Input: "Clean up this function" (AI-style with docstring and line comments)
Pythondef summarize_orders(orders): """ Summarize order data. Args: orders: A list of order dictionaries. Returns: A dictionary with revenue, pending, and average. """ # Filter completed orders completed = [o["amount"] for o in orders if o["status"] == "completed"] # Count pending orders pending = sum(1 for o in orders if o["status"] == "pending") # Return the summary return { "revenue": sum(completed), "pending": pending, "average": sum(completed) / len(completed) if completed else 0, }
Output:
Pythondef summarize_orders(orders): completed = [o["amount"] for o in orders if o["status"] == "completed"] return { "revenue": sum(completed), "pending": sum(1 for o in orders if o["status"] == "pending"), "average": sum(completed) / len(completed) if completed else 0, }
Example 2:
Input: a generic helper used once — def process_data(data): return [x.strip().lower() for x in data] called at a single site.
Output: inline it at the call site as [name.strip().lower() for name in raw_names], named for what it actually holds.
Example 3:
Input:
JavaScript////////////////////////////////////// // SECTION: AUTH HANDLERS ////////////////////////////////////// function login(req, res) { // ---- validate input ---- if (!req.body.email) return res.status(400).end(); // do the login ... }
Output:
JavaScriptfunction login(req, res) { if (!req.body.email) return res.status(400).end(); ... }
Recommendation▾
Consider trimming the Final Check section since it largely duplicates the Workflow checklist
Best Practices
- Name things for their domain role (
pending_orders, notresultortemp). - Validate at boundaries, not with exhaustive checks everywhere.
- Match the repo's existing type-hint and formatting density — don't impose a new style.
- Stay in scope: no unrequested files, dependencies, or tests.
- Explain reasoning to the user in chat, not in the file.
Common Pitfalls
- Typing
"""or/** */out of habit on a new function. - Writing a comment that starts with "Initialize", "Loop", "Check", "Return", "This", or "Note" — delete it.
- Adding any separator/banner line, short or long, to mark a section.
- A comment longer than the line it describes.
- Commenting a line you already named well.
- Explaining what instead of why.
- Leaving a TODO instead of finishing or omitting it.
- Hand-aligning or reformatting code the user didn't ask you to touch.
Final Check
- No comment restates code
- No long docstring, Args/Returns block, or TODO
- No separator/banner lines anywhere, of any length or symbol
- Names are domain-specific
- Diff is small; nothing unrequested
- Formatter, linter, and tests pass