Write code like a human will maintain it
Engineers debate how large language models are changing code quality and maintainability, arguing that AI-generated code often duplicates logic, overcomments, and ignores abstractions unless explicitly guided. Many advocate retaining “clean code” practices—good naming, DRY helpers, small functions, clear intent comments—and using tools like linters, structured prompts, and automated review workflows so agents produce code humans (and future agents) can safely extend. Others push back that business pressure, context limits, and emerging AI-centric workflows mean teams must balance human readability with the reality that future maintenance may be done primarily by machines.
Comments, naming, and readability
- Many prefer minimal comments and clear naming over heavy commenting.
- Redundant “explain what the code does” comments are seen as noise and likely to rot; comments should explain “why”, not “what” or “how the framework works”.
- Some advocate a literate-programming-like workflow (write prose/intent first, then code), but acknowledge this often devolves into restating the code.
- Consensus: good names, simple structure, and occasional “here be dragons / rationale” comments are ideal.
LLM-generated comments and style
- Strong frustration with LLMs producing verbose, low-value comments, historical notes, and implementation-process chatter.
- Models often describe language basics, surrounding code quirks, or caller behavior, breaking encapsulation and quickly going stale.
- Attempts to constrain this via CLAUDE.md / AGENTS.md rules help somewhat but are inconsistently followed; negative instructions (“don’t do X”) are especially flaky.
Productivity vs maintainability with AI
- Some claim 10x feature/bugfix throughput by shipping whatever passes tests and letting AI “deal with the mess later”.
- Others warn this slop compounds: duplicated logic, diverging business rules, and nested defensive layers make future AI and human work slower and riskier.
- There’s debate whether short-term speed will be offset by long-term complexity, especially in large codebases.
Prompts, checklists, and review workflows
- Many use project-level CLAUDE.md / AGENTS.md plus explicit “/review” commands with long checklists (DRY, style, duplication, dead code, tests, docs).
- Some split review into multiple specialized passes (security, accessibility, performance, simplification) and even multi-model adversarial review.
- Others report diminishing returns as instruction lists grow; models still ignore basic rules (e.g., git usage), requiring system-level guardrails.
Traditional tooling and guardrails
- Static analyzers, linters, code-formatters, duplication detectors, and pre-commit/CI checks are widely recommended as non-stochastic baselines.
- Some write custom linters or compiler-level checks to enforce things LLMs routinely violate (no magic numbers, no dynamic imports, doc/test requirements).
Roles of humans vs AI
- Several developers now use LLMs mainly for exploration, refactoring, and review, but still hand-write core code.
- Others embrace AI-heavy workflows, accepting that humans may no longer hold a full mental model of the system and instead rely on strong harnesses and tooling.
- Underneath, many emphasize: maintainable structure, DRYness, and clear abstractions still matter—for both humans and agents consuming the code later.