3

I was asked to review and handle merge request for a code base, which has been contributed by dozens of programmer with basically no regulation (or perhaps there was but nobody follows), so I set up executable regulation, making clear details like formatting, naming rules, how you should build control flow etc.

Things just start working for about 2 weeks and my manager ask me to present "some proofs" that code quality is improving. As much as I can argue "It takes time. You can't expect shit fixed in 2 weeks." He could still ask for such proofs in maybe a month or 2 from now on. Showing him the code or commits one by one may not really help, because this code base won't go into shit in the first place should he cares enough to go through them line by line.

So, how do I prepare for proofs to show "our code quality is getting better" on that day?

Improve this question
4
  • 3
    IMO only way to "measure" improved/worsening code quality is from changing cycle time. The main goal of improved quality is to maintain ability to quickly and efficiently make changes. This can be direcly seen from changing cycle times from moment work is started to the moment value is delivered.
    – Euphoric
    Apr 24 at 4:53
  • 1
    "so I set up executable regulation, making clear details like formatting, naming rules, how you should build control flow etc." - a full set of irrelevancies, practically the whole works!
    – Steve
    Apr 24 at 7:17
  • 2
    It's an industry standard, it's "best practice". Proving that it helps your particular operation is not possible. Measuring if the number of bugs found by the user (or tester) is something but you probably do not have the back-data and you are building different things today from what you were building yesterday, possibly with different people. You basically have to believe that 1.) People make mistakes and 2.) Other people are more likely to spot those mistakes than the people who made them. If your management cannot believe that or feels it is not worth the effort, you cannot help them.
    – Martin Maat
    Apr 24 at 9:40
  • Proof of "improvement" needs some indicators on the previous state to compare against. How you describe the situation seems to indicate there isn't any....
    – tofro
    Apr 28 at 9:38

5 Answers 5

Reset to default
3

How has the situation come about where you've been tasked with "improving code quality" and some sort of quantified metric or "proof" is being demanded after two weeks of shuffling the code formatting?

It seems to me like there is considerable confusion on all sides.

Quality

It's widely accepted that there are no effective metrics for measuring the whole quality of arbitrary code.

It's also widely accepted that simple transformations by automated tools do not appreciably improve quality.

Code formatting does matter for readability, but nobody ever encounters code that is just great except for the formatting.

Seriously poor formatting is typically a sign that the developer had no attention to detail or any other care in the world - and the problems with quality won't just be with the formatting.

Fuss about formatting more often amounts to good developers arguing amongst themselves about brace position or other style trivia that doesn't deserve attention, or it amounts to expecting the guy who looks after the dungeon to start eating with a knife and fork at the king's table (i.e. setting a standard too far away from the competence of the given developer, the underlying problem being recruitment or salary factors being mismatched to the need for developers with real skills).

Real improvements in code quality, where there is a real deficit, typically take a considerable amount of time to implement - a good guideline is that whatever number of man-hours it took to write the code under consideration, it will take at least that number of man-hours for a new developer to revisit.

If the poor quality is localised, then fine, but if it permeates the whole application then change can be a considerable amount of work, if one developer is attempting to take on what has already taken several developers several years to produce.

Proof

The proof of code quality will always be mainly in the judgment of those who work with the software. That is, those who read and write code, and who keep possession of the main and most detailed understanding of the system.

The code can be in poor condition quite some time before the problems become manifest to non-technical staff, such as through the frequency of bugs and breakdowns, the inability to adapt the code to even small changes in business circumstances, or the obvious flight of expertise and inability to retain developers.

Once these kinds of symptoms are manifest, there is often no hope of recovering the existing code base, and the cost of development (or the cost of lost opportunity for development that can't happen) changes up a step.

Your manager asking for "proof" of improved quality suggests either he's asking for independent metrics that don't exist, or he's asking at least for a very convincing explanation of the importance of the changes you've made and the worthiness of allocating your time to it.

Dangers

There's a danger here that you might very well know the problems with the code, but not necessarily the actual solutions.

There's also a danger of your manager commissioning or trying to assess the results of work he doesn't understand, and of you not being in a position to improve that understanding.

If your manager has asked you to "improve code quality", I'd take asking for results two weeks later as screaming siren that his understanding of what he is managing is as far away from reality as Hades from Elysium.

If you've asked for the right to allocate your time to "improving code quality" because you know it to be poor, then clearly what you haven't done is brief him at the outset about the scale of proposed work and likely timelines.

You might need to think about how exactly to explain the relevant points and correct the course.

Improve this answer
3
  • "Seriously poor formatting is typically a sign that the developer had no attention to detail or any other care in the world" - sometimes it's a sign of a tool that insists on applying it's own bad formatting.
    – gnasher729
    Apr 24 at 12:46
  • @gnasher729, indeed, the generated SQL in Microsoft Access being an infamous example that comes straight to my mind!
    – Steve
    Apr 24 at 13:14
  • Steves logic seems sound - the only thing I would add is you may want to collect some info (read: survey) from the rest of the team as to whether they support the direction you are moving (good/bad/do something different) - i.e. make this a team decision.
    – DavidT
    Apr 24 at 16:51
2

quality of a code base

There are many ways to define that. And there are many ways to quantify that. There are many metrics to measure code quality. From your manager's POV, the most important metric would be "the number of bugs discovered during testing". Or "the number of bugs and problems discovered by the customer". If that number decreases, then you surely reached some desirable goal. If the code is beautiful, but the number of bugs increases, then something needs to be tuned.

Note: As mentioned in the comments, it is difficult to show a direct correlation between some random activity (coding, testing, debugging...) and the overall quality of the product. There are countless metrics that can be used to "measure software development". However, for a practical, results-oriented manager, a metric like cyclomatic complexity reduced from 50 to 20 is going to be just noise that he will most likely ignore.

Improve this answer
8
  • 1
    When the number of bugs discovered during testing decreases, this can have different causes: the developers introduced less bugs in first place (which might be caused by better code quality), or the testing process (the "afterwards" testing where bugs are counted) got worse. Or, the developers improved a better up-front automated testing process which prevented more bugs to slip through to the "afterwards" testing process. Or the devs only took tasks from the backlog over the last two months which were easier to implement. ....
    – Doc Brown
    Apr 24 at 6:21
  • 1
    ... or, developer staff had some changes - Joe Coybow-Coder went on a 4 weeks vacation, and was replaced by Jane Pedantic-Coder. My point is, it is pretty hard (if not impossible) to measure code quality by counting bugs over time.
    – Doc Brown
    Apr 24 at 6:23
  • @DocBrown: your comment considers only short term analysis. On any short time period, the results can have ups and downs. But the general trend (medium term and especially long term) should go downwards, after any improvements to the processes (coding, testing, reporting, trainings for the staff...).
    – virolino
    Apr 24 at 6:32
  • @DocBrown: also, the test team should be independent from the development team (both writing the testcases AND running the tests) - exactly for avoiding false reporting or flawed test procedures.
    – virolino
    Apr 24 at 6:34
  • 2
    Your argument is flawed - the longer the evaluated period is, the more likely it becomes other factors than code quality will influence the number of bugs over time. It will be even more harder to measure the influence of code quality that way. I think there must be a better way to demonstrate that improved code quality improves the development process to a manager.
    – Doc Brown
    Apr 24 at 6:36
0

During the code review, write down how the code was improved, how bugs were detected and fixed, how code structure was improved.

Fixing formatting, unless the formatting was really bad, doesn't improve your code. Fixing method names so that they clearly indicate what a method does without me having to read the documentation, that improves code. There have been cases where I couldn't think of a good method name and left a note for the reviewer to improve it (if possible).

Improve this answer
0

Perhaps, you could look for a different way to communicate what code quality is. A way not adhered to programming best practices, principles or specific metrics only but to how those things change the way developers work and perform.

Sometimes, we can't prove the existence of things just by looking at them, but we can prove their existence by the effects they cause.

Your PM is likely unable to see the quality in any source code, but you can instruct him/her to see the effects. For example, formatting code should result in faster merge requests, causing fewer downtimes for developers. The PM may or may not be tracking these downtimes, but he/she knows how often developers have claimed that merging code is hard or getting harder. Or he/she knows how often the merges result in bugs or errors. Know this, anything impacting the planning will trigger an alarm to the PM. If you can correlate the improvements you (and the team) have done with fewer alarms and planning deviations, you are proving quality improvement.

Sure, low code quality is likely to have the same effects on my project and yours, but it's likely we both have different priorities. So we'll measure quality in different ways. But in any case, we need references, milestones, something we can look at and compare, and something to project a trend with.

The easy would be to do a static analysis of the code and generate reports to compare over time. For example, you could implement SonarQube in the organization. Then choose the metrics more relevant to you and the PM. Make a dashboard anyone can see, including the PM. Instruct the PM on how to read the metrics and indicators. The PM is likely to have been tracking the costs of the project and the adherence to the planning, so the only he/she has to do is correlate what the dashboard shows with the current state of the planning and be sensitive to changes in the trends. Concrete numbers are not that important.

Finally, you have to make sure him/her understands that no static analysis will measure aspects like readability or design. That's up to the team to do. Readability may not appear in the dashboard, but the side effects will be noticeable to the PM if it causes deviations from the planning. The PM will know about readability issues by remembering excuses from developers. However, the PM should not wait that late. The PM should be proactive and perform some retrospectives with the team to bring to light this kind of issue.

In a nutshell, as issues correlated to the state of the source code shrink, their effects on the planning will shrink too. That's (with your help) what the PM should focus on.

Improve this answer
0

There are many things that you can call quality, but one option is to think of quality as how easy the code is to work with. Code that's easier to work with is likely to be delivered and operated more effectively, so I suggest tracking the Dora metrics for software delivery performance as an indirect way of tracking quality. These should be a leading indicator for organisational performance that depends on software quality.

You could set up systems to track these, or you may be able to track them well enough by simply surveying yourself and your colleagues about them - the Dora research is survey based after all.

You can find the metrics in the 2022 Accelerate State of Devops Report from Google Cloud and Dora. There are four relatively well known metrics, often called the "four key metrics" or "accelerate metrics", and one new one:

  • Lead time for changes
  • Mean Time To Recovery
  • Deployment Frequency
  • Change Failure Rate,

and

  • Reliability
Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.