From 20y experience and CS degree, I see software engineering as a constant struggle against accidental complexity. Like quicksand, every movement you make will pull you deeper, even swimming in the right direction. And like entropy, it governs all things (there are no subfields that are free of complexity). It even seems impossible to give a meaningful, useful definition, perhaps by necessity. All is dark.

But now and then, something beautiful happens. Something that used to be dreadful, becomes "solved". Not in the mathematical strict sense, but some abstraction or some tool eliminates an entire class of issues, and once you know it you can barely imagine living without it. That's why I keep coming back to it, I think.

As a species, I think we are in the infancy stages of software engineering, and perhaps CS as well. There's still lots of opportunity to find better abstractions, big & small.

Related problem I've been exploring lately: finding which files are most worth refactoring, with complexity as one of the inputs.

I've built a small, opinionated tool for that [1]. It can rank files by a "Refactor Priority" score based on structural signals - size, callable burden, cyclomatic complexity, nesting - with churn and co-change from local git history layered on top.

It's more of an exploratory tool than a general solution, but it's been practically useful for quickly spotting painful files.

Part of why it was built: keeping coding agents in check. They tend to produce code that gets complex fast, don't feel the complexity building up, and eventually start making changes that break things. So the tool helps me catch files that are getting out of hand before that happens. It can also generate a refactoring prompt explaining why a given file is problematic - as a conversation starter for the agent.

The article gave me a few more metric ideas to try, thanks.

[1] https://github.com/etechlead/token-map

To do a Simple Cyclomatic Complexity check, operating on the principle that secure systems are simple systems, you can use https://github.com/nocomplexity/codeaudit or try the wasm version on https://nocomplexity.com/codeauditapp/dashboardapp.html

Complexity directly impacts security. Simple systems are: Maintainable: Easier to change and manage. Reliable: Less prone to logic errors. Testable: Easier to validate and test.

Claude Code and others often write code that is more complex than it needs to be. It would be nice to measure the code complexity before and after a change made by the agent, and then to tell it: "You increased code complexity by 7%. Can you find a simpler solution?".

Wonderful article, thanks for sharing. These complexity definitions and the connection to linguistic complexity are useful. Also enjoyed this line:

> The cognitive complexity of a function can only be determined by the reader, and only caring about the reader can enable the writer to improve the learning experience.

This is a very informative article. I hadn't really considered the complexity of the code before, so this is very helpful.