AI Skill Report Card
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 Start13 / 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.
- Run the repo's formatter, linter, and tests.
Recommendation▾
Add a second, more substantial before/after example (e.g., a larger function or class with over-engineered structure) to show the skill handling bigger scope creep, not just comment stripping.
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 — never a block.
Never write:
- docstrings with
Args:,Returns:,Raises:,Example: - comments restating the next line ("Initialize...", "Loop over...", "Check if...", "Return...")
- "This function...", "Note that...", "Here we...", "Step 1:", section banners
- TODO or placeholder comments
- emoji, ASCII art, 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
- Match repo's formatting/typing style, don't over-format
- Run formatter, linter, tests
- Re-read diff for scope creep and leftover comments
Recommendation▾
Include an example of handling naming/renaming decisions explicitly (good vs bad renamed variable) since 'domain role naming' is emphasized but only shown once briefly.
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.
Examples16 / 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.
Recommendation▾
Show a 'bad outcome' example — e.g., a case where comment removal goes too far and strips a genuinely necessary one — to reinforce the exception-not-default nuance with a concrete counterexample.
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
"""out of habit on a new function. - Writing a comment that starts with "Initialize", "Loop", "Check", "Return", "This", or "Note" — delete it.
- 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
- Names are domain-specific
- Diff is small; nothing unrequested
- Formatter, linter, and tests pass