Get Higher Quality and Productivity by tackling the Broken Window Effect
The broken window theory states visible signs of disorder create an environment for more disorder. A study by Keizer et al. (2008) found that littering was more likely to occur in an environment where there was already garbage on the ground, compared to a clean environment. The broken window effect has been observed in some studies, but not in others. It is not a well-established or universally accepted phenomenon, but rather a hypothesis that requires more empirical testing and theoretical refinement. Still from my perspective the broken window effect can be observed when dealing with static code check issues or code coverage.
In this blog I want to show some building blocks in the context of software engineering, which can help to avoid that there is a vicious circle towards more disorder.
How does this relate to software engineering?
Software development is all about details and if we don’t act on any deviations in design even minor in nature, we would likely to end up with a project which will inherit complexity. Crucial factor that makes software rot is the way the growth of the code is managed in terms of complexity, and quality.
We often tend to make the quality suffer due to the time crunch to make our project deliver on time causing complexity creep due to forced efforts to meet timelines. “Quick and Dirty” duct tapes as fixes to deliver code leads to poor quality and the system becomes impossible to maintain. In cases where complexity is high, developers consider rewrite or major refactoring leading to frustration, because it costs too much time and energy.
Examples for a broken window in software engineering are:
- If you already have higher number of static code checks issues in your code base, you do not recognize if your change adds new ones.
- If you have a low code coverage, adding new tests is almost not visible in the overall code coverage and maybe your colleagues do not add unit test, so the situation is still deterioating.
- With flaky tests you think that each failing test is a false positive
How to avoid this situation?
What are measures to avoid the broken window effect:
- Fine Tune Requirements: For any project, it is tempting to go into executing mode. It is always a good practice to clear the “why” before making or moving into implementation. Having well-defined targets for a measure to track the progress will help in reducing over-engineering and reduce complexity in code. For ensuring that the requirements are written well, you can define a Definition of Ready.
- Zero Tolerance Threshold: For new projects you can introduce a zero tolerance threshold, which means it is not allowed to merge changes with static code check issues or low code coverage into the master. This helps to sustain the productivity of your team. E.g. without such a policy, static code check issues pile up and sometimes important issues are not recognized, since there already too many.
- Fix flaky tests: Fragile Tests should be made stable immediately or put into quarantine. More details you can find in the blog Flaky Tests at Google and How We Mitigate Them.
- Do Code Reviews or Pair Programming for the stuff, which cannot be tested by tools. E.g. the maintainability and quality of your tests and Clean Code principles.
- Code Metrics: There are some indicators, which could help to detect problematic code (e.g. cyclomatic complexity).
- Automatic Fixing: Formatting issues can be corrected automatically.
How to get out of the situation if the code is not clean
Some issues can be fixed automatically.
For static code check issues: Set a threshold based on the current number of found static code check issues. This ensures that no new issue is introduced. After refactorings and cleanups adjust the threshold to the lower number.
Code Coverage: There are tools, which check the code coverage for new code and other tools can check if there is a positive trend in your code coverage.
In this chapter I connect to automatic checks and automated correction to avoid or mitigate the broken window effect. This automation frees up more time to take care about other aspects of clean code.
Automatic Checks and Corrections for Java
Absolute Thresholds for Code Coverage can e.g. be done with Maven and JaCoCo:
- Automated code coverage of unit tests with JaCoCo and Maven
- How to fail a maven build, if JUnit coverage falls below certain threshold
Code Style can be done with PMD and / or SpotBugs. For automatic correction there is also java plugin for prettier – did not try it yet.
Absolute Thresholds for Code Coverage can e.g. be done with KARMA and Istanbul:
Code Style issues can be found and some can be automatically fixed with ESLint. ESLint can also be used for formatting, but the recommendation for formatting is Prettier. The automatic correction can be triggered in a pre-commmit hook (e.g. with Husky).
Automatic Checks and Corrections for ABAP
More information on how to setup static code checks can be found in:
- ABAP Test Cockpit (ATC): For static code checks and (mass) quick fixes you can use ATC.
- ABAP cleaner applies 55+ cleanup rules to ABAP code at a single keystroke. ABAP cleaner is a configurable tool with the “ambition to automate whatever can be automated” with respect to Clean ABAP code style. Keep in mind that many clean code and style guide rules cannot be automatically corrected, you still e.g. need to take care of modularization, testability or good naming. It is available both as a plug-in to ABAP Development Tools (ADT, a.k.a. ABAP in Eclipse) and as a stand-alone version, and allows you and your team to configure exactly which of the 55+ cleanup rules you want to apply. Like Pretty Printer, the cleanup is then done with a single keystroke, cleaning any selected amount of code from a single statement or method up to a whole multi-thousand-line code document. After two years of development and evaluation as an Inner Source project at SAP, ABAP cleaner is now Open Source. It can be freely used — and is also open for new ideas and contributions!
Clean Code still matters for engineers
However, not all of these rules can be automatically corrected by tools or programs. For example, a tool might fix the indentation or spacing of your code, but it cannot tell you if your code is well-structured or easy to understand. You still have to pay attention to some important aspects of coding, such as modularization, testability, good naming and many other aspects. These aspects require your own judgment and skill, and they can make a big difference in the quality and readability of your code. For instance, modularization means that you divide your code into smaller and independent units or modules that have clear responsibilities and interfaces. This makes your code easier to maintain, reuse and test. Testability means that you write your code in a way that allows you to verify its correctness and functionality using automated tests. This helps you to find and fix bugs faster and ensure that your code meets the requirements and expectations. Good naming means that you choose meaningful and consistent names for your variables, functions, classes and other elements of your code. This makes your code more expressive and understandable for yourself and others who might read or modify it in the future.
You can learn more about the applied clean code practices and principles in the style guide repository and the bookds.
From the Clean Code Books
This chapter is a summary from the books on Clean ABAP and Clean SAPUI5. More details on this and other topics can be found in
Hey Klaus Haeuptle ,
I had a look at ABAP Cleaner today (looks very promising!). Standalone works fine, but I seem not be be able to install the ADT-AddOn. -> Opened an Issue for that, hope that's fine.
I installed the add-on (I have the latest version of Eclipse and ADT), and it worked nicely.
Issue is fixed, I can confirm it works very nicely!
I hat to add two lines to
eclipse.ini, right after
Thank you for open sourcing the abap-cleaner! This is a very valuable tool, and something missing from the ABAPer's toolbox for some time (as I mentioned here on a previous post of yours). I know many engineers will be happy to be able to automate some of the clean code rules.
I'll be testing it out soon, and look forward to contributing as well!
I also tried installing the ADT Addon and came across the problem with trust/certificates which I could resolve by changing eclipse.ini.
But the installation fails anyway because of errors due to osgi repositories that can't be found.
This seems to go back to an incompatible Eclipse release. I'm on 2022-03 currently. It seems to work with 2022-12 and 2023-03.
It would be helpful to mention the compatibility to eclipse releases somewhere on the git site or even inlude ABAP Cleaner at https://tools.hana.ondemand.com.
Could you create an issue in the repository, so that the ABAP Cleaner team can have a look at it: Issues · SAP/abap-cleaner (github.com)