Lizard: A Straightforward Tool to Tame Your Complex Code

We've all been there. You open up a codebase—maybe one you wrote six months ago, maybe one a colleague built—and you feel that familiar sense of dread. The functions are long, the nesting is deep, and understanding the flow feels like untangling a ball of yarn. Keeping code complexity in check is crucial for maintenance, but the tools to do it can sometimes feel overly complex themselves.

Enter Lizard. It’s a simple, extensible code complexity analyzer that just gets the job done. No fuss, no complicated configuration. You point it at your code, and it gives you the metrics you need to spot trouble before it becomes a real problem.

What It Does

Lizard is a command-line tool that analyzes the source code of over 50 programming languages and spits out key complexity metrics. Its primary focus is on Cyclomatic Complexity, a classic measure created by Thomas McCabe that counts the number of independent paths through your code. In simpler terms, it tells you how many if, for, while, and case statements are branching your code out.

Alongside this, it also reports on:

• The Number of Parameters per function.
• The Number of Lines of Code per function.
• The Number of Tokens per function.

By default, it gives you a clean, readable summary right in your terminal, showing you exactly which files and functions are the most complex and might need a refactor.

Why It's Cool

So, why choose Lizard over other complexity analyzers? A few things make it stand out.

First, it's incredibly easy to use. You don't need a PhD in static analysis to run lizard /your/code/path and get immediate, actionable feedback. It works out of the box for a massive list of languages, from Python and Java to C++ and even Swift.

Second, it's fast. It doesn't try to build your entire project or resolve all dependencies. It scans the files directly, which means you get results almost instantly, even on large codebases. This speed makes it perfect for integrating into your pre-commit hooks or CI/CD pipeline to catch complexity creep as it happens.

Finally, it's highly extensible. You can write custom plugins in Python to add your own metrics or analysis rules. You can also easily ignore certain files, exclude third-party libraries, or set custom complexity thresholds that match your team's coding standards.

How to Try It

Getting started with Lizard is a one-liner. Install it using pip:

pip install lizard

Then, navigate to your project's directory and run it:

lizard .

You'll get an output that looks something like this, immediately highlighting the most complex parts of your code:

================================================
  NLOC    CCN   token  PARAM  length  location
------------------------------------------------
       5      2      29      1       5 get_file_info@31-35@./lizard.py
       5      1      25      1       5 get_all_source_files@37-41@./lizard.py
...

Want to see a specific file? Just run lizard path/to/your/file.py. You can also use the -x flag to exclude directories (like -x "./test*") or -T to set a threshold for the number of parameters to warn about.

Final Thoughts

In the daily grind of hitting deadlines and shipping features, it's easy for code complexity to silently balloon. Lizard acts as a quick and reliable sanity check. It doesn't preach or enforce rules; it just gives you the data. I find it most useful as a first-pass tool during code reviews or as a gatekeeper in a continuous integration system to flag PRs that might need a second look.

It won't write the code for you, but it will absolutely help you identify which parts of your code are becoming difficult to read, test, and maintain. Give it a run on your current project—you might be surprised by what you find.

@githubprojects