Skip to main content

Code Quality Avoiding AI Fingerprints

Code Quality: Avoiding Obvious AI Fingerprints

Goal: Keep our projects professional. Avoid comments, naming, and patterns that scream "AI-generated" and embarrass us in reviews or open source.

What to avoid

Comments

  • Redundant: "This function returns the user by ID." when the method is getUserById().
  • Filler: "Here we iterate over the list." / "Let's validate the input." / "It's worth noting that..."
  • Hedging: "We might want to consider..." / "It could be useful to..." / "You may wish to..."
  • Meta: "Best practice is to..." (unless citing a spec or security guideline).
  • Placeholder debt: "TODO: implement" / "FIXME" with no issue link. Prefer GitLab issues; link in comment if needed.

Naming and style

  • Over-verbose variables: theUserObjectThatWeNeedToValidate instead of user or candidate.
  • Generic names: processData(), handleRequest(), performAction() with no domain meaning.
  • Repetition: Same phrase in every file ("Follows Drupal coding standards and best practices") — say it once in the module README or wiki.

Structure

  • Copy-paste blocks: Nearly identical code in multiple places. Extract to a shared function or service.
  • Wall of comments: Every line explained. Comment why, not what; only when non-obvious.

What to do instead

  • Comments: Explain why (business rule, security, workaround). Omit when the code is clear.
  • Names: Domain terms and project conventions. Short where scope is obvious.
  • TODOs: Create a GitLab issue; put the issue reference in the comment, or remove the TODO.
  • Best practices: Reference a standard (e.g. "OWASP", "Drupal security team") or link to wiki/spec; avoid generic "best practice" lines.

Review before commit

  • Skim new comments for "we", "let's", "consider", "best practice", "it is important".
  • Check that descriptions and docblocks add information; remove filler.
  • Ensure no standalone "TODO" or "FIXME" without an issue or removal plan.

Where this lives

  • Authority: This wiki page. Refer new contributors and AI assistants here.
  • Config: NAS config/AGENTS.md points to the Drupal demos plan and to this page for code quality.