How to Identify Code Quality Issues

There's a common belief in our industry that technical debt sneaks into a codebase over time, often blamed on external pressure like deadlines, staff turnover, context switches, manager decisions, etc. But is that really what happens? Some of the worst code I've ever reviewed contained thousands of lines of code with God Functions, way too many responsibilities, painful code duplication, implicit dependencies which make every change brittle, excess conditional logic in a shape that's capable of melting your brain faster than a GPU without heatsink -- you name it. How did we get there? Most likely, the code was bad from the start and its future evolution merely dug that hole deeper. The evidence? A fascinating study investigated 200 open source projects for code smells, and then backtracked each of those code problems to identify the commit that introduced the root cause. The surprising conclusion is that such problems are introduced already upon the creation of those classes! 💡 If code problems are present from the start, then our practices and tools need to take that fact into account. However, existing code may of course also turn bad with a single commit. When that happens, the affected code exhibits specific trends that differ from how clean code evolves. (You see an example in the graph). ✅ Collaborate early -- don't wait for a review where it's "too expensive" to reject the complete implementation. ✅ Use strong quality gates for any new code. Automate. ✅ Track evolutionary trends in code health. Act on any signs of trouble. By applying these principles, we prevent technical debt instead of managing its consequences.

Code reviews are about catching “evolvability defects” as much as bugs. When most teams think of code review, they think about spotting bugs. But here’s the reality: only 25% of issues flagged in reviews are actual bugs. The rest? They’re deeper problems that make a codebase harder to maintain and scale over time. These are what we call “evolvability defects.” Evolvability defects don’t crash your system today, but they lead to bottlenecks, tech debt, and friction that will cost your team down the line. Here’s a breakdown of what they look like: → 10% of issues are basic inconsistencies—alignment, spacing, structure. → 33-44% are documentation gaps—comments with missing context, unclear variable names, or lacking structure. → 44-55% are structural problems—inefficient organization, shortcuts that don’t scale, design choices that slow down future development. For developers, effective code review means more than finding bugs. It’s about ensuring code is readable, maintainable, and built to last. For engineering leaders, it’s about risk management. When code review prioritizes evolvability defects, your team’s velocity tomorrow is as strong as it is today. Is your team identifying evolvability defects? They’re what separate short-term fixes from long-term success. #codereview #bito #ai

𝗪𝗵𝗮𝘁 𝗮𝗿𝗲 𝘀𝗼𝗺𝗲 𝗰𝗿𝗶𝘁𝗶𝗰𝗮𝗹 𝗦𝗼𝗻𝗮𝗿𝗤𝘂𝗯𝗲 𝗾𝘂𝗮𝗹𝗶𝘁𝘆 𝗺𝗲𝘁𝗿𝗶𝗰𝘀? To maximize the effectiveness of SonarQube in maintaining and improving code quality, here are some best practices for SonarQube analysis: 𝟭. 𝗜𝗻𝘁𝗲𝗴𝗿𝗮𝘁𝗲 𝗦𝗼𝗻𝗮𝗿𝗤𝘂𝗯𝗲 𝗲𝗮𝗿𝗹𝘆 𝗶𝗻 𝘁𝗵𝗲 𝗱𝗲𝘃𝗲𝗹𝗼𝗽𝗺𝗲𝗻𝘁 𝗽𝗿𝗼𝗰𝗲𝘀𝘀 Integrate SonarQube into your CI/CD pipeline to ensure that code quality checks are performed automatically with every build. The sooner we start, the more accurate our data will be. It is more accurate than introducing it later in the process; you will get many more false positives as SonarQube analyzes the code as it is written, not after. 𝟮. 𝗗𝗲𝗳𝗶𝗻𝗲 𝗰𝗹𝗲𝗮𝗿-𝗾𝘂𝗮𝗹𝗶𝘁𝘆 𝗴𝗮𝘁𝗲𝘀 Define quality gates with specific thresholds for critical metrics such as bugs, vulnerabilities, code smells, and coverage. This helps enforce quality standards. Also, configure your CI/CD pipeline to fail builds if the quality gate criteria are not met, ensuring issues are addressed promptly. 𝟯. 𝗜𝗻𝘁𝗲𝗴𝗿𝗮𝘁𝗲 𝗦𝗼𝗻𝗮𝗿𝗤𝘂𝗯𝗲 𝗶𝗻 𝘁𝗵𝗲 𝗖𝗜/𝗖𝗗 𝘀𝗲𝗿𝘃𝗲𝗿 When we enable the automatic usage of SonarQube during the build and PR process, we get immediate feedback about our code quality. This helps us to improve the code before it is merged into the codebase. This also allows our reports to always be up to date and not rely on any manual process. 𝟰. 𝗣𝗿𝗶𝗼𝗿𝗶𝘁𝗶𝘇𝗲 𝗶𝘀𝘀𝘂𝗲𝘀 𝗯𝗮𝘀𝗲𝗱 𝗼𝗻 𝘀𝗲𝘃𝗲𝗿𝗶𝘁𝘆 To maintain your application's stability and security, address critical and significant issues (bugs and vulnerabilities) first. Then, incrementally tackle code smells and minor issues to gradually improve code maintainability without overwhelming the team. 𝟱. 𝗗𝗼𝗻’𝘁 𝗶𝗴𝗻𝗼𝗿𝗲 𝗶𝘀𝘀𝘂𝗲𝘀 If we ignore issues, we will postpone the problem and increase technical debt, which we don’t want to do. We should fix the issues when they happen. If there are issue types we don’t want to fix, we can adjust the SonarQube ruleset and exclude those rules. 𝟲. 𝗠𝗶𝗻𝗶𝗺𝗶𝘇𝗲 𝗰𝗼𝗱𝗲 𝗱𝘂𝗽𝗹𝗶𝗰𝗮𝘁𝗶𝗼𝗻 Review the codebase regularly for duplicates and refactor them into reusable components or functions. SonarQube can help identify these duplications. 𝟳. 𝗠𝗶𝗻𝗶𝗺𝗶𝘇𝗲 𝗧𝗲𝗰𝗵𝗻𝗶𝗰𝗮𝗹 𝗗𝗲𝗯𝘁 The technical debt ratio is the estimated time to fix code issues divided by the project development time. Aim to keep this ratio below 5% to ensure the project remains manageable. Allocate a portion of the team development time to addressing technical debt. This could involve refactoring, improving test coverage, or resolving code smells. 𝟴. 𝗠𝗮𝗶𝗻𝘁𝗮𝗶𝗻 𝗵𝗶𝗴𝗵 𝘁𝗲𝘀𝘁 𝗰𝗼𝘃𝗲𝗿𝗮𝗴𝗲 Aim for high test coverage, typically 60-80%. This ensures that most of the codebase is tested, reducing the likelihood of bugs slipping through. Use tools like JaCoCo or Cobertura to measure test coverage. #technology #softwareengineering #programming #techworldwithmilan #coding

The time between introducing a defect and fixing it is one of the most important metrics in software engineering. The closer that gap is to zero, the better. Not all defects are bugs that break things. Low-quality code, functions that are too long, nesting that's too deep, complexity that's too high, is a defect too. It works, but it degrades your codebase over time. After building 30+ repositories with AI coding tools, I've seen this play out at scale. These tools generate more code faster, which means there's more to manage. Functions balloon to 60 lines. Nesting goes four levels deep. Cyclomatic complexity creeps past 15. You don't notice until every change gets harder. Code review catches it, but too late. By the time a reviewer flags a 40-line function, the AI has already built three more on top of it. The fix is enforcing quality at the moment of creation. I built a set of Claude Code PostToolUse hooks (scripts that run after every file edit) that analyze every file Claude writes or edits and block it from proceeding when the code violates quality thresholds. Thresholds are configurable per project. Six checks, enforced at the moment of creation: → Cyclomatic complexity > 10 → Function length > 20 lines → Nesting depth > 3 levels → Parameters per function > 4 → File length > 300 lines → Duplicate code blocks (4+ lines, 2+ occurrences) All six checks run on Python with no external dependencies. JavaScript, TypeScript, Java, Go, Rust, and C/C++ get complexity, function length, and parameter checks via Lizard. When a violation is found, Claude gets a blocking report with the specific refactoring technique to apply: extract method, guard clause, parameter object. It fixes the problem and tries again. In a recent 50-file session, Claude resolved most violations within one or two retries, with blocks dropping from 12 in the first 20 writes to 2 in the last 30. Hooks handle measurable structural quality so I can focus reviews on design and correctness. If a threshold is wrong for a specific project, you change the config. → ~100-300ms overhead per file edit on modern hardware → Start with one hook (function length > 20 lines) and see how it changes what your AI produces The full writeup covers: → The hook architecture and how PostToolUse triggers work → A before/after showing how a 45-line nested function gets split into three focused helpers → Why hooks complement CLAUDE.md rules rather than replacing them Link in comments 👇