How to Disable a Local Code Smell with a Code Comment Directive

Overview

Most Code Health findings are worth fixing. Every so often, though, a specific function has a good reason to keep a pattern CodeScene would otherwise flag: a hand-tuned hot path, a generated function, a legacy interface you can't reshape yet. For exactly that situation, CodeScene lets you disable a function-level smell locally, with a directive written as a source code comment, right above the function it applies to.

This article covers the directive syntax, exactly how it behaves, which smells it can target, and how to use it without quietly eroding the signal Code Health is supposed to give you.

The @codescene Directive, in Three Lines

A directive is a comment placed directly above a function, naming the smell you want CodeScene to ignore for that function only:

// @codescene(disable:"Complex Method") void execute(ProgramOptions* options) { // ...lots of complex code here... }

You can disable more than one smell in the same directive:

// @codescene(disable:"Complex Method", disable:"Bumpy Road Ahead") void execute(ProgramOptions* options) { // ...lots of complex code along a bumpy road... }

Or wave off everything CodeScene would otherwise flag on that function with the disable-all shortcut:

// @codescene(disable-all) void execute(ProgramOptions* options) { // ...lots of complex code along a bumpy road... }

The Rules of the Road

Directives are simple, but a few behaviors are worth knowing before you rely on them:

  • Function-level only. The @codescene directive supports function smells. You can't use it to disable file-level issues, such as Lines of Code or Low Cohesion — those apply to the file as a whole, not to one function.

  • Scoped to the next function. A directive always applies to the function or method immediately following it — nothing above it, nothing further down the file.

  • Comment blocks are fine. A directive can be part of a larger, multi-line comment (a /** ... */ block in Java, for example) — it doesn't need a line of its own.

  • Names must match exactly. The string inside the disable instruction has to be an exact match of the code smell name shown in CodeScene's virtual code review. An unknown or misspelled name is silently ignored, and the finding keeps firing — so if a directive doesn't seem to be working, check the exact wording in your review first.

  • Nothing flies under the radar. The virtual code review includes a non-blocking warning informing you about the use of directives in the code, together with their impact. Transparency is the point: a directive changes what CodeScene reports, not what it sees.

Which Smells Can You Target?

Directives work on function-level and implementation-level smells — the two categories CodeScene attaches to a specific function rather than a whole file. That includes findings such as:

  • Brain Method (aka God Function) — a complex function that centralizes a class or module's behavior and becomes a local hotspot.

  • Complex Method — many conditional statements (if, for, while), measured via cyclomatic complexity.

  • Large Method — a function with enough lines of code that it's harder to follow.

  • Primitive Obsession — heavy reliance on built-in primitives (integers, strings, floats) instead of a domain type that encapsulates validation and meaning.

  • DRY violations — duplicated logic that tends to change together in predictable patterns.

  • Nested Complexity — if statements nested inside other if statements or loops, which raises defect risk.

  • Bumpy Road — a function that hasn't encapsulated its responsibilities, so it reads as several loosely related chunks of logic strung together.

  • Complex Conditional — a branch condition (if, for, while) built from multiple logical operators (AND/OR).

File-level smells, Lines of Code, Low Cohesion, and similar, sit outside what a directive can touch; those need a different fix (see Additional Resources below).

Treat the list above as a guide to what's possible, not a copy-paste source: always confirm the exact smell name against your own virtual code review before writing the directive, per the exact-match rule above.

Document the Why

A directive with no explanation is a mystery for the next person who opens the file. The syntax lets you add the rationale inline, on the same line as the directive:

// @codescene(disable-all) Rewrite next week (2020-01-30)

A ticket reference and a date work just as well as a note like "rewrite next week" — the goal is that anyone who finds the directive later can trace back to why it exists and judge whether the reason still holds.

Staying Visible: Reviews Catch Every Directive

Because a directive lives in the source, it travels with the function through every future review and refactor — but CodeScene doesn't rely on someone happening to notice it. Two things keep directives visible on their own:

  • The virtual code review shows a non-blocking warning about any directive in the code, along with its impact.

  • The Pull Request review summary flags any new directive introduced in that change — so a directive shows up for review the moment it's added, not months later when someone stumbles on it.

Best Practices

  • Be restrictive with directives. The clear majority of Code Health findings are real problems that should be refactored — a directive is the exception, not the default response to a failing check.

  • Make it a habit to inspect new directives. The Pull Request review summary is built for exactly this — use it to review every new directive the way you'd review any other change.

  • Document the rationale. Write it into the directive itself, and reference the evidence (a ticket, a profiling result, a benchmark) that justified the exception. That's what lets the team revisit it later and confirm it's still needed.

A Worked Example

A NAND driver's interrupt service routine intentionally inlines a large, branch-heavy state machine to hit its cycle budget. The Complex Method rule flags it, correctly, since it's built almost entirely from conditional branches. Profiling shows that splitting the function up to satisfy the rule adds real, measured latency to the interrupt path.

Rather than suppress the finding through the UI or turn off the rule project-wide, the team agrees on the exception and documents it directly on the function:

// NAND driver interrupt service routine  // @codescene(disable:"Complex Method") // Hand-tuned for cycle budget; team-agreed // after profiling (JIRA-4821, 2026-08). void nand_isr_handle_event(uint32_t status) {  if (status & DMA_DONE) {  ...  } else if (status & ECC_ERROR) {  ...  } else if (status & TIMEOUT) {  ...  }  ... }

The directive silences Complex Method on this one function. Every other function in isr.c, and every other file in the codebase, still gets the full check and the directive itself shows up in the virtual code review and in the Pull Request summary, so it's reviewed like any other change rather than disappearing into the file.

Key Takeaways

  • A @codescene directive disables a named function-level smell on the function immediately below it. It can't reach file-level issues like Lines of Code or Low Cohesion.

  • The smell name must match exactly what your virtual code review shows; get it wrong and the directive is silently ignored.

  • Directives are transparent by design: the virtual code review flags their use and impact, and the Pull Request summary calls out every new one.

  • Use a directive to record a specific, evidence-backed exception, agreed as a team and documented with the reason, not as a quick way to make a warning disappear.

Additional Resources