Drupaltools Best Practices

Drupal Best Practices Auditor

Source: https://raw.githubusercontent.com/theodorosploumis/drupal-best-practices/refs/heads/master/README.md Covers Drupal 8.x and above.

Step 1 — Detect context

Before auditing, identify:

1. No input provided — ask the user to paste code, a file path, or a folder structure.
2. Drupal version — if unknown, assume 9.x/10.x and flag if advice may differ.
3. What was given — detect the type(s) from the table below and audit only the applicable categories.
4. Minified or generated files — warn that results may be incomplete; ask for source.

Step 2 — Audit categories

Check every applicable category below. For each category not applicable to the input, write one line: "Not applicable: [category]."

A. Naming conventions

• Machine names: letters only, no special chars, no spaces, singular (not plural).
• Custom module names must be prefixed with projectmachinename_.
• Theme machine name: one word, no theme in the name, no base-theme name embedded.
• Field machine names follow pattern: field_[content_type]_[short_name] for specific fields; field_[generic_name] for shared fields.
• View modes: generic names not tied to a field or dimension (e.g. wide not wide_1920x570).
• Views: no _1 suffix on display machine names; remove default suffix.
• Image styles: generic, not dimension-based (e.g. large not large_600x300).
• User roles: one word (e.g. author not authors, admin not super_administrator).
• Avoid names that shadow existing Drupal core or contrib names.

B. Site building

• Nodes: no nodes used as dynamic blocks; use custom block types or entities instead.
• Revisions: not enabled by default unless content requires workflow states.
• Taxonomy: terms used only when categorized pages are needed, not just for filtering.
• Fields: all fields have a Description; image field directories are named (not default date-based); gif removed from image fields unless required.
• Views: one display per View (except when required); Format > Show: Content used (not fields); Ajax disabled by default; "No results" text provided; Access set to Permission not Role; unused Views disabled.
• Menus: real <menu> elements used, not block-as-menu workarounds; <nolink> for placeholder paths.
• Text formats: one HTML-allowed format; CKEditor buttons match allowed HTML tags; no PHP in WYSIWYG.
• Users/roles: roles split by persona; no shared accounts; authenticated role has no extra permissions.

C. Theming

• One base theme only; subtheme name independent of base theme name.
• Preprocess functions used for custom attributes/classes, not inline Twig logic.
• CSS classes: twig- prefix for Twig-added classes, js- prefix for JS-triggered classes.
• No non-semantic utility classes (e.g. clearfix, full-width as CSS class names).
• SASS/SCSS used; large SCSS files split by entity or concern.
• Twig templates overridden only from the source module (not copied from random places).
• Special pages templated: 404, 403, maintenance, login.
• Path aliases not used as CSS class hooks.
• Organize the twig files on a custom theme on a folder with the name original (just the copied twig templates from base theme or module) and a folder override where you have the twig templates you override. A twig with the same name should exist on both the original and override folder.

D. Coding (PHP / module)

• All functions/classes documented with docblocks.
• Private functions at bottom of file; never called outside declaring module.
• Custom permissions defined per module; never reuse existing permissions.
• Permission titles start with a verb: "View …", "Administer …", "Delete …".
• Machine names are human-readable (no abbreviations like field_mytype_ac_y_d).
• Drupal coding standards followed: https://www.drupal.org/docs/develop

E. Scaffolding / project structure

• drupal/recommended-project used as base; not core's own composer.json.
• One settings.php that includes environment-specific files; settings.php tracked in git; env-specific files are not.
• Credentials and passwords in .env files, never in tracked files.
• config/ folder outside web root, tracked in git.
• vendor/ outside web root.
• Composer used for all dependencies; only composer.json and composer.lock tracked.
• Specific version pinned for all packages (e.g. "drupal/core": "10.2.3" not "^10").
• Patches via cweagans/composer-patches using static patch files only.
• Less modules is better; prefer core modules over contrib when possible.

F. Third-party libraries

• Check if the library is already in Drupal core before adding it.
• Prefer specific releases over branches.
• Prefer local copies over CDN for performance.

G. Infrastructure / environment

• dblog module not enabled on live; use monolog or syslog.
• Cron run externally (not via Drupal core cron).
• Dev modules listed (should not be on live): devel, stage_file_proxy, reroute_email, etc.

Step 3 — Output format

For each issue found:

Issue N — [Short title]

• Category: [A–G from above]
• Severity: [Critical / High / Medium / Low]
• Affected code or name: [paste verbatim]
• Problem: [One or two sentences.]
• Fix: [Corrected code, name, or action.]

If a category has no issues: "No issues found: [category]." If everything passes: write a short paragraph summarising what is correct and why.

Severity scale

Machine name quick reference

External references

• Best practices source: https://github.com/theodorosploumis/drupal-best-practices
• Drupal development standards: https://www.drupal.org/docs/develop
• Drupal coding standards: https://www.drupal.org/docs/develop/standards
• Drupal-spec-tool (automated testing): https://github.com/acquia/drupal-spec-tool
• Composer best practices: https://www.lullabot.com/articles/drupal-8-composer-best-practices
• Module incompatibilities (Acquia): https://docs.acquia.com/acquia-cloud/develop/drupal/module-incompatibilities