<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Alex Arbatskiy</title>
    <description>The latest articles on DEV Community by Alex Arbatskiy (@alex_arbatskiy).</description>
    <link>https://dev.to/alex_arbatskiy</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4219857%2F6ad78ac9-5037-40db-a98f-6c01ef683cc7.png</url>
      <title>DEV Community: Alex Arbatskiy</title>
      <link>https://dev.to/alex_arbatskiy</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/alex_arbatskiy"/>
    <language>en</language>
    <item>
      <title>Tests Pass. Your Code Still Gets Harder to Read.</title>
      <dc:creator>Alex Arbatskiy</dc:creator>
      <pubDate>Sun, 22 Nov 2026 03:13:07 +0000</pubDate>
      <link>https://dev.to/alex_arbatskiy/tests-pass-your-python-still-gets-harder-to-read-12d9</link>
      <guid>https://dev.to/alex_arbatskiy/tests-pass-your-python-still-gets-harder-to-read-12d9</guid>
      <description>&lt;p&gt;&lt;em&gt;Gate complexity regressions on the code you actually change, not the whole repo.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;LLM-assisted coding agents in the IDE and CLI make it easy to ship the next feature fast. The catch is that each follow-up edit tends to add another branch, wrapper, or "just in case" handler. One pass is fine. Five passes on the same function, and you can end up with code that still passes tests but reads like it was designed by a committee.&lt;/p&gt;

&lt;p&gt;Cyclomatic complexity won't always tell you that story. Two functions with the same number of paths can feel very different to read:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="c1"&gt;# Cyclomatic complexity: 4, cognitive complexity: 3&lt;/span&gt;
&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;route_flat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s2"&gt;"a"&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s2"&gt;"b"&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s2"&gt;"c"&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s2"&gt;"default"&lt;/span&gt;


&lt;span class="c1"&gt;# Cyclomatic complexity: 4, cognitive complexity: 6&lt;/span&gt;
&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;route_nested&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
                &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s2"&gt;"a+b+c"&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s2"&gt;"default"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;An agent "improving" error handling often drifts from the first shape toward the second. Tests still green. Review still looks plausible. Maintenance gets worse anyway.&lt;/p&gt;

&lt;p&gt;We already fail CI on formatting, lint, and type errors. Complexity belongs in that same bucket: deterministic, diff-scoped, not a vibes check from the model.&lt;/p&gt;

&lt;h2&gt;
  
  
  Three numbers worth tracking (Python)
&lt;/h2&gt;

&lt;p&gt;None of these scores mean "good code." They're tripwires for "this change made things harder to follow or harder to test."&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Metric&lt;/th&gt;
&lt;th&gt;What it catches&lt;/th&gt;
&lt;th&gt;Tool&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Cognitive complexity&lt;/td&gt;
&lt;td&gt;Nesting and flow that's hard to hold in your head&lt;/td&gt;
&lt;td&gt;&lt;a href="https://github.com/rohaquinlop/complexipy" rel="noopener noreferrer"&gt;complexipy&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cyclomatic complexity&lt;/td&gt;
&lt;td&gt;Too many independent paths through a function&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://docs.astral.sh/ruff/rules/complex-structure/" rel="noopener noreferrer"&gt;Ruff C901&lt;/a&gt; or &lt;a href="https://radon.readthedocs.io/" rel="noopener noreferrer"&gt;Radon&lt;/a&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Test coverage&lt;/td&gt;
&lt;td&gt;Code you can change without a safety net&lt;/td&gt;
&lt;td&gt;&lt;a href="https://pytest-cov.readthedocs.io/" rel="noopener noreferrer"&gt;pytest-cov&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Track them separately. Cognitive complexity cares about nesting; cyclomatic complexity counts decision points (paths through the function). Coverage answers a different question: whether you have tests at all.&lt;/p&gt;

&lt;h2&gt;
  
  
  Regression gates beat repo-wide thresholds
&lt;/h2&gt;

&lt;p&gt;Don't start with "every function in the monolith must score under 10." You'll fight legacy debt forever.&lt;/p&gt;

&lt;p&gt;Start with: &lt;strong&gt;on functions this PR touches, don't let cognitive complexity cross your threshold or creep upward without noticing.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://complexipy.com/" rel="noopener noreferrer"&gt;complexipy&lt;/a&gt; compares against a git ref or your staged changes and can fail the run when the gate fails:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;pip install complexipy
complexipy . --diff main --max-complexity-allowed 15
&lt;span class="c"&gt;# before commit (staged vs HEAD):&lt;/span&gt;
complexipy . --staged --max-complexity-allowed 15
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With &lt;code&gt;--diff&lt;/code&gt;, complexipy prints regressions and improvements. The process exits non-zero when a &lt;strong&gt;new&lt;/strong&gt; or &lt;strong&gt;regressed&lt;/strong&gt; function ends up &lt;strong&gt;above&lt;/strong&gt; &lt;code&gt;--max-complexity-allowed&lt;/code&gt; (default &lt;code&gt;15&lt;/code&gt; if you omit the flag). A small bump that stays under the cap still shows up in the report, but it does not fail the gate by itself. For legacy codebases, &lt;a href="https://complexipy.com/adoption/" rel="noopener noreferrer"&gt;snapshots&lt;/a&gt; record known offenders so CI blocks only new violations and functions that get worse.&lt;/p&gt;

&lt;p&gt;For cyclomatic complexity, enable Ruff's C901 rule (not enabled by default):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight toml"&gt;&lt;code&gt;&lt;span class="k"&gt;[tool.ruff.lint]&lt;/span&gt;
&lt;span class="na"&gt;extend-select&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"C901"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;

&lt;span class="k"&gt;[tool.ruff.lint.mccabe]&lt;/span&gt;
&lt;span class="na"&gt;max-complexity&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Run &lt;code&gt;ruff check&lt;/code&gt; on the same paths you changed. Coverage is coarser: think "don't drop coverage on touched files" rather than chasing a perfect percentage.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;New functions&lt;/strong&gt; have no prior score on &lt;code&gt;main&lt;/code&gt;. The same &lt;code&gt;--max-complexity-allowed&lt;/code&gt; ceiling covers them, or a &lt;a href="https://complexipy.com/adoption/" rel="noopener noreferrer"&gt;snapshot baseline&lt;/a&gt; if you're adopting on brownfield code. See &lt;a href="https://complexipy.com/ci/" rel="noopener noreferrer"&gt;CI integration&lt;/a&gt; for GitHub Actions and pre-commit.&lt;/p&gt;

&lt;h2&gt;
  
  
  Don't trust the model. Give it rules
&lt;/h2&gt;

&lt;p&gt;Paste something like this into your agent instructions:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;On every modified Python function: run &lt;code&gt;complexipy&lt;/code&gt; with &lt;code&gt;--diff&lt;/code&gt; or &lt;code&gt;--staged&lt;/code&gt; and fix cognitive complexity regressions. Run &lt;code&gt;ruff check&lt;/code&gt; with C901 enabled. Do not add nesting or branches "for safety" unless the task requires it. Keep or improve test coverage on changed code; run the relevant tests before you finish.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That turns "write clean code" into commands that exit non-zero.&lt;/p&gt;

&lt;h2&gt;
  
  
  What this won't catch
&lt;/h2&gt;

&lt;p&gt;Metrics can be gamed. Extracting five one-line helpers might flatten cyclomatic scores while scattering logic. A giant &lt;code&gt;if/elif&lt;/code&gt; ladder can look "simple" on paper and still be miserable. That's why cognitive complexity plus coverage deltas matter alongside cyclomatic checks, and why a human still reads the diff.&lt;/p&gt;

&lt;p&gt;Sometimes complexity should go up. The point isn't minimal scores. It's stopping silent erosion across repeated AI edits.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where to start
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Add &lt;code&gt;complexipy . --diff main --max-complexity-allowed 15&lt;/code&gt; (tune the number) to CI or pre-commit.&lt;/li&gt;
&lt;li&gt;Turn on Ruff &lt;code&gt;C901&lt;/code&gt; with a sensible &lt;code&gt;max-complexity&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Post complexity deltas in PR comments before you hard-fail the whole team.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Agents can dump a lot of code in one go. Asking for a second pass with a concrete target (&lt;code&gt;route_nested&lt;/code&gt; cognitive score went up, flatten the nesting) costs little next to shipping it.&lt;/p&gt;




&lt;p&gt;Have you wired cognitive or cyclomatic complexity checks into AI-assisted workflows? Curious what broke in practice and what you'd do differently.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>python</category>
      <category>softwaredevelopment</category>
    </item>
  </channel>
</rss>
