CodeQuality Archives - Page 4 of 5 - Software Quality Blog

CodeIt.Right Rules Explained, Part 10

October 10, 2017Erik Dietrich1

Like any good habit, I’ve settled into a cadence with the CodeIt.Right Rules Explained posts.? They’re coming about once per month or so, and each one offers a deep dive into three of CodeIt.Right’s?rules.? As always, I’ll start by citing my two personal rules about static analysis, along with a brief explanation.

Never implement a suggested fix without knowing what makes it a fix.
Never ignore a suggested fix without understanding what makes it a fix.

This isn’t a rhetorical game.? I could condense the statements and say ?learn the reasoning behind all suggested fixes.? ?But I say it the way that I do to call your attention to a decision that you face when it comes to static analysis warnings. ?Every time you encounter a warning, you must either choose to ignore the feedback or to address it. ?And regardless of which you chose, you should really understand the logic behind the suggestion. ?Otherwise, how can you possibly make the right call?

In that spirit, I?m going to offer up explanations for yet another three?CodeIt.Right?rules today.

(more…)

CodeIt.Right Rules Explained, Part 9

September 12, 2017Erik DietrichNo Comments

In what has become roughly a monthly affair, I’ll do another CodeIt.Right Rules Explained post today. ?This marks the ninth such post and roughly nine months of the series. ?In a now-familiar refrain, I’ll start off by citing my two personal rules about static analysis followed by a brief explanation.

Never implement a suggested fix without knowing what makes it a fix.
Never ignore a suggested fix without understanding what makes it a fix.

It might seem I’m playing rhetorical games here. ?After all, I could condense this to say “learn the reasoning behind all suggested fixes.” ?But I say it the way that I do to call your attention to a decision that you face when it comes to static analysis warnings. ?Every time you encounter a warning, you must either choose to ignore the feedback or to address it. ?And regardless of which you chose, you should really understand the logic behind the suggestion. ?Otherwise, how can you possibly make the right call?

In that spirit, I’m going to offer up explanations for another three CodeIt.Right rules today.

Avoid Unsealed Attributes

Let’s start off with something conceptually easy to understand, at least in terms of the problem. ?You’ve no doubt encountered the attribute construct before, whether you realize it or not. ?Here’s a quick code example.

[TestMethod]
public void Adding_10_And_15_Returns_25()
{
    var calculator = new Calculator();

    int result = calculator.Add(10, 15);

    Assert.AreEqual<int>(25, result);
}

That thing at the very top? ?TestMethod? ?That’s called an attribute.

In .NET, attributes amount to declarative metadata about the code element they describe. ?For instance, we use the attribute in the code sample to declare that this is a test method. ?You write this code to opt into the MS Test framework. ?The framework then looks for that attribute and treats any method decorated with it as a unit test method.

How do you get access to this magic? ?Let’s look at a trivial, ridiculous, and hopefully memorable example. ?First, I declare the attribute.

public class ApprovedByErikAttribute : Attribute
{

}

With that on the books, I can now meander through the codebase, making my opinion felt. ?Let’s say I encounter a class called Circle. ?It’s a bit simplistic, but it’s off to a good start. ?I approve this class! ?Let’s let everyone know.

[ApprovedByErik]
public class Circle
{
    private readonly int _radius;

    public Circle(int radius)
    {
        _radius = radius;
    }
}

Alright, everything looks great here. ?Except I run a CodeIt.Right analysis on this and I see a warning: “avoid unsealed attributes.” ?Well, inheritance is certainly less fashionable these days, but CodeIt.Right flags this as a?performance issue. ?What gives?

Well, you access this attribute metadata via reflection, which, as it turns out, is expensive in and of itself. ?You have to pay the piper for this magic. ?But doing this with unsealed attributes is even more expensive since the .NET framework methods for accessing attribute information search the entire inheritance hierarchy by default. ?Sealing your class basically tells them not to bother looking any further. ?It’s also a really easy fix: just add the keyword “sealed” to your attribute class and call it a day.

Avoid Excessive Complexity

Let’s change gears here and switch over to a CodeIt.Right rule under the heading “maintainability.” ?This one counsels you to “avoid excessive complexity,” and I won’t include a code sample here. ?Why? ?Because in order to do that, I’d have to come up with a ridiculous method that would take up half of the space of this post. ?I’ll come back to that, though.

When CodeIt.Right refers here to “complexity,” it’s not offering some vague, subjective take. ?Rather, it refers to something measurable and specific. ?I’m talking about the idea of cyclomatic complexity. ?Cyclomatic complexity measures the number of independent paths through a method. ?So if you have a method that just returns the sum of two integers, then you have cyclomatic complexity of one. ?But if you add a guarding if condition, you now have a cyclomatic complexity of two.

To conceptualize the idea, think in terms of control flow logic. ?If and else conditionals add to a method’s cyclomatic complexity. ?So do while loops, for loops, ternary operators, and switch statements. ?The more decision logic occurring in a method, triggering different ways to step through it, the higher the cyclomatic complexity.

Out of the box, CodeIt.Right will flag methods with cyclomatic complexity of more than 25. ?That means it will flag any methods with more than 25 independent paths through them. ?Make no mistake — that is an insanely complex method that will cause you maintenance headaches. ?And now you can understand why I wouldn’t want to dream up and post such a thing. ?It’d just be a tortured rat’s nest of nested loops, conditionals, and perhaps even some goto logic for good measure.

Enforce Warning Level 4

Last up today, let’s look at something a bit off the beaten path. ?This falls under the heading of “general” in CodeIt.Right’s rule categorizations. ?And it speaks to properties of your project, rather than of your code.

If you right click a project in Visual Studio and select “project properties” (or use keyboard shortcut alt + enter), you get a screen that lets you modify aspects of the project itself. ?Select the “build” tab, and you can modify settings about how MS Build compiles the project. ?Of interest today, we have the “Warning Level” setting under “Errors and warnings,” as shown here.

By default, your projects come with warning level 4 pre-selected. ?And 4 is also the highest level of warnings. ?You can check out the details of each warning level here.

The warning messages to which it refers show up in your “errors” window when you build your project. ?That window will show you any compiler errors, but also compiler warnings, such as unreachable code or unused variables.

When you select something less than 4, you’re telling your build to show you fewer warning messages. ?If you go all the way down to 0, you’re telling it show you no warnings at all: “If you’re technically able to build this, then build it and tell me nothing.” ?CodeIt.Right warns you about this practice because it’s generally a bad idea to ignore compiler warnings. ?The vast majority of the time, they’re warning you about something legitimately wrong with your code.

If, on occasion, the compiler warning system yields some false negatives, you have other recourse to ignore them. ?You don’t need to engage in blanket disabling. ?CodeIt.Right warns you about this course of action because it’s almost certainly overkill for what you want to accomplish.

Until Next Time

I’ve tried to offer yet another eclectic mix of code issues in this post. ?I started with a lesser known bit about defining your own attributes that actually relates to performance. ?Then I took you through the general issue of high cyclomatic complexity and wound up with a general suggestion not to ignore wholesale warnings in your codebase.

And that last bit of advice, in fact, parallels my general advice on static analysis. ?The compiler is yet another form of static analyzer, and you should probably heed its advice or else have a very, very good reason not to.

Learn more how CodeIt.Right can help you automate code reviews and improve the quality of your code.

CodeIt.Right Rules Explained, Part 8

August 15, 2017Erik DietrichNo Comments

Today, I’ll do another installment of the CodeIt.Right Rules Explained series.? This is post number eight in this series.? As always, I’ll start off by citing my two personal rules about static analysis, along with an explanation.

Never implement a suggested fix without knowing what makes it a fix.
Never ignore a suggested fix without understanding what makes it a fix.

This might seem glib.? After all, I could just as easily say, “Learn the reasoning behind all suggested fixes.”? But I say it the way I do to highlight the decision you face when confronted with static analysis warnings.? In all cases, you must actively choose to ignore the feedback or to address it.? And for both options, you need to understand the logic behind the suggestion from the warning.

In that spirit, I’m going to offer up explanations for three more CodeIt.Right rules today.

(more…)

Zeus leading the charge of code review myths.

Examining Code Review Myths

August 8, 2017Erik Dietrich3

Alexander Pope once opined that a little learning can be a dangerous thing. ?When we learn just enough to hear something that suits our agenda, we have a cognitive bias that encourages us to stop right there. ?Quit while you’re ahead, as it were.

This dynamic gives rise to misconceptions. ?They go by various names: urban legends, myths, canards, tall tales, etc. ?Obviously, this occupies a prominent role in our world, to have such a rich tapestry of synonyms.

I won’t delve any further into the psychology behind this. ?That’s not my area of expertise. ?But I would like to recount (and clear up) some of the myths I hear about code review in my travels.

As a consultant, I find myself in a lot of software shops, observing a lot of people. ?As a result, I feel as though I have a particularly rich set of misconceptions from which to draw. ?IT management consultants are usually there either to drive change or to act as incidental parties to it. ?That change makes people uneasy, which causes objections to surface. ?Some of those objections are perfectly legitimate. Some of them are nonsense.

Let’s focus today on the nonsense. ?What are some code review myths?

(more…)

There's an intense pressure to finish software quickly, which puts strain on manual code reviews.

Software Grows Too Quickly for Manual Review Only

July 27, 2017Erik Dietrich2

How many development shops do you know that complain about having too much time on their hands? ?Man, if only we had more to do. ?Then we wouldn’t feel?bored between completing the perfect design and shipping to production … said no software shop, ever. ?Software proliferates far too quickly for that attitude ever to take root.

This happens in all sorts of ways. ?Commonly, the business or the market exerts pressure to ship. ?When you fall behind, your competitors step in. ?Other times, you have the careers and reputations of managers, directors, and executives on the line. ?They’ve promised something to someone and they rely on the team?to deliver. ?Or perhaps the software developers apply this drive and pressure themselves. ?They get into a rhythm and want to deliver new features and capabilities at a frantic pace.

Whatever the exact mechanism, software tends to balloon outward at a breakneck pace. ?And then quality scrambles to keep up.

Software Grows?via Predictable Mechanisms

While the motivation for growth may remain nebulous, the mechanisms for that growth do not. ?Let’s take a look at how a codebase accumulates change. ?I’ll order these by pace, if you will.

Pure maintenance mode, in SDLC parlance.
Feature addition to existing products.
Major development initiatives going as planned.
Crunches (death marches).
Copy/paste programming.
Code generation.

Of course, you?could offer variants on these themes, and they do not have?mutual exclusivity. ?But nevertheless, the idea remains. ?Loosely speaking, you add code sparingly to legacy codebases in support mode. ?And then the pace increases until you get so fast that you literally write programs to write your programs.

The Quality Conundrum

Now, think of this in another way. ?As you go through the list above, consider what quality control measures tend to look like. ?Specifically, they tend to vary inversely with the speed.

Even in a legacy codebase, fixes tend to involve a good bit of testing for fear of breaking production customers. ?We treat things in production carefully. ?But during major or greenfield projects, we might let that slip a little, in the throes of productivity. ?Don’t worry — we’ll totally do it later.

But during a death march? ?Pff. ?Forget it. ?When you slog along like that, tons of defects in production qualifies as a good problem to have. ?Hey, you’re in production!

And it gets even worse with the last two items on my bulleted list. ?I’ve observed that the sorts of shops and devs that value copy/paste programming?don’t tend to worry a lot about verification and quality. ?Does it compile? ?Ship it. ?And by the time you get to code generation, the problem becomes simply daunting. ?You’ll assume that the tool knows what it’s doing and move on to other things.

As we go faster, we tend to spare fewer thoughts for quality. ?Usually this happens because of time pressure. ?So ironically,?when software grows?the fastest, we tend to check it the least.

(more…)

Many things cause poor code quality, turning your code to spaghetti.

5 Things Responsible for Your Poor Code Quality

July 25, 2017Erik Dietrich2

All right. Let’s get the obvious thing out of the way right up front.

One could easily argue that code quality (and poor code quality) is subjective. ?You use camel case while I use Pascal case, and we could argue about the “quality” of the code in those terms. ?But I have no interest in that.

So instead, let’s talk about code quality in terms of observable outcomes. ?You may look at a codebase and, based on your experience, conclude that this unfamiliar code is of poor quality. ?Who wrote this, anyway!? ?But you do that without understanding outcomes. ?Does this code serve its purpose in production with minimal issues? ?Does the application satisfy its constituents? ?And does the team consistently deliver features on time and on budget? ?At best, you can make educated guesses about that information when simply reading the code.

I have a bit of an advantage in my study of codebases. ?You see, I work as a consultant, specializing in codebase assessments, developer training, and team strategy. ?So I receive phone calls from clients when the external qualities are demonstrably poor — in other words, when the code has many issues, the application fails to satisfy its constituents, and the team misses deadlines and causes budget overruns. ?It turns out no prospective clients ever call to say, “Hey, things are GREAT, but will you come take a look at what we’re doing anyway?”

So I wind up looking at codebase after codebase that produces bad outcomes. ?I assess and analyze these things, and I’ve come away with some properties of the code that invariably correlate bad outcomes. ?Here are five things contributing to your poor code quality.

(more…)

Automated Code Review to Help with the Unknowns of Offshore Work

April 12, 2017Erik DietrichNo Comments

I like variety.? In pursuit of this preference, I spend some time management consulting with enterprise clients and some time volunteering for “office hours” at a startup incubator.? Generally, this amounts to serving as “rent-a-CTO” for startup founders in half hour blocks.? This provides me with the spice of life, I guess.

As disparate as these advice forums might seem, they often share a common theme.? Both in the impressive enterprise buildings and the startup incubator conference rooms, people ask me about offshoring application development.? To go overseas or not to go overseas?? That, quite frequently, is the question (posed to me).

I find this pretty difficult to answer absent additional information.? In any context, people asking this bake two core assumptions into their question.? What they really want to say would sound more like this.? “Will I suffer for the choice to sacrifice quality to save money?”

They assume first that cheaper offshore work means lower quality.? And then they assume that you can trade quality for cost as if adjusting the volume dial in your car.? If only life worked this simply.

What You Know When You Offshore

Before going further, let’s back up a bit.? I want to talk about what you actually know when you make the decision to pay overseas firms a lower rate to build software.? But first, let’s dispel these assumptions that nobody can really justify.

Understand something unequivocally.? You cannot simply exchange units of “quality” for currency.? If you ask me to build you a web app, and I tell you that I’ll do it for $30,000, you can’t simply say, “I’ll give you $15,000 to build one-half as good.”? I mean, you could say that.? But you’d be saying something absurd, and you know it.? You can reasonably adjust cost by cutting scope, but not by assuming that “half as good” means “twice as fast.”

Also, you need to understand that “cheap overseas labor” doesn’t necessarily mean lower quality.? Frequently it does, but not always.? And, not even frequently enough that you can just bank on it.

So what do you know when you contract with an inexpensive, overseas provider?? Not a lot, actually.? But you do know that your partner will work with you mainly remotely, across a great deal of distance, and with significant communication obstacles.? You will not collaborate as closely with them as you would with an employee or a local vendor.

The (Non) Locality Conundrum

So you have a limited budget, and you go shopping for offshore app dev.? You go in knowing that you may deal with less skilled developers.? But honestly, most people dramatically overestimate the importance of that concern.

What tends to torpedo these projects lies more in the communication gulf and less in the skill.? You give them wireframes and vague instructions, and they come back with what they think you want.? They explain their deliveries with passable English in emails sent at 2:30 AM your time.? This collaboration proves taxing for both parties, so you both avoid it, for the most part.? You thus mutually collude to raise the stakes with each passing week.

Disaster then strikes at the end.? In a big bang, they deliver what they think you want, and it doesn’t fit your expectations.? Or it fits your expectations, but you can’t build on top of it.? You may later, using some revisionist history, consider this a matter of “software quality” but that misses the point.

Your problem really lies in the non-locality, both geographically and more philosophically.

When Software Projects Work

Software projects work well with a tight feedback loop.? The entire agile movement rests firmly atop this premise.? Stop shipping software once per year, and start shipping it once per week.? See what the customer/stakeholder thinks and course correct before it’s too late.? This helps facilitate success far more than the vague notion of quality.

The locality issue detracts from the willingness to collaborate.? It encourages you to work in silos and save feedback for a later date.? It invites disaster.

To avoid this, you need to figure out a way to remove unknowns from the equation.? You need to know what your partner is doing from week to week.? And you need to know the nature of what they’re building.? Have they assembled throwaway, prototype code?? Or do you have the foundation of the future?

Getting a Glimpse

At this point, the course for enterprises and startups diverge.? The enterprise has legions of software developers and can easily afford to fly to Eastern Europe or Southeast Asia or wherever the work gets done.? They want to leverage economies of scale to save money as a matter of policy.

The startup or small business, on the other hand, lacks these resources.? They can’t just ask their legion of developers to review the offshore work more frequently.? And they certainly can’t book a few business class tickets over there to check it out for themselves.? They need to get more creative.

In fact, some of the startup founders I counsel have a pretty bleak outlook here.? They have no one in their organization in a position to review code at all.? So they rely on an offshore partner for budget reasons, and they rely on that partner as expert adviser and service provider.? They put all of their eggs in that vendor’s basket.? And they come to me asking, “have I made a good choice?”

They need a glimpse into what these offshore folks are doing, and one that they can understand.

Leveraging Automated Code Review

While you can’t address the nebulous, subjective concept of “quality” wholesale, you can ascertain properties of code.? And you can even do it without a great deal of technical knowledge, yourself.? You could simply take their source code and run an automated code review on it.

You’re probably thinking that this seems a bit reductionist.? Make no mistake — it’s quite reductionist.? But it also beats no feedback at all.

You could approach this by running the review on each incremental delivery.? Ask them to explain instances where it runs afoul of the tool.? Then keep doing it to see if they improve.? Or, you could ask them to incorporate the tool into their own process and make delivering issue-free code a part of the contract.? Neither of these things guarantees a successful result.? But at least it offers you something — anything — to help you evaluate the work, short of in-depth knowledge and study yourself.

Recall what I said earlier about how enterprises regard quality.? It’s not as much about intrinsic properties, nor is it inversely proportional to cost.? Instead, quality shows itself in the presence of a tight feedback loop and the ability to sustain adding more and more capabilities.? With limited time and knowledge, automated code review gives you a way to tighten that feedback loop and align expectations.? It ensures at least some oversight, and it aligns the work they do with what you might expect from firms that know their business.

Tools at your disposal

SubMain offers CodeIt.Right that easily integrates into Visual Studio for flexible and intuitive automated code review solution that works real-time, on demand, at the source control check-in or as part of your build.

Related resources

eBook – Automated Code Review with CodeIt.Right

Learn more how CodeIt.Right can help you automate code reviews and ensure the quality of delivered code.

Automation and the Art of Software Maintenance

March 7, 2017Erik Dietrich3

I have long since cast my lot with the software industry.? But, if I were going to make a commercial to convince others to follow suit, I can imagine what it would look like.? I’d probably feature cool-looking, clear whiteboards, engaged people, and frenetic design of the future.? And a robot or two.? Come help us build the technology of tomorrow.

Of course, you might later accuse me of bait and switch.? You entered a bootcamp, ready to build the technology of tomorrow.? Three years later, you found yourself on safari in a legacy code jungle, trying to wrangle some SharePoint plugin.? Erik, you lied to me.

So, let me inoculate myself against that particular accusation.? With a career in software, you will certainly get to work on some cool things.? But you will also find yourself doing the decidedly less glamorous task of software maintenance.? You may as well prepare yourself for that now.

The Conceptual Difference: Build vs Maintain

From the software developer’s perspective, this distinction might evoke various contrasts.? Fun versus boring.? Satisfying versus annoying.? New problem versus solved problem.? My stuff versus that of some guy named Steve that apparently worked here 8 years ago.? You get the idea.

But let’s zoom out a bit.? For a broader perspective, consider the difference as it pertains to a business.

blog-automation-software-maintenance-1 Build mode (green field) means a push toward new capability.? Usually, the business will regard construction of this capability as a project with a calculated return on investment (ROI).? To put it more plainly, “we’re going to spend $500,000 building this thing that we expect to make/save us $1.5 million by next year.”

Maintenance mode, on the other hand, presents the business with a cost center.? They’ve now made their investment and (at least partially) realized return on it.? The maintenance team just hangs around to prevent backslides.? For instance, should maintenance problems crop up, you may lose customers or efficiency.

Plan of Attack: Build vs Maintain

Because the business regards these activities differently, it will attack them differently.? And, while I can’t speak to every conceivable situation, my consulting work has shown me wide variety.? So I can speak to general trends.

In green field mode, the business tends to regard the work as an investment.? So, while management might dislike overruns and unexpected costs, they will tend to tolerate them more.? Commonly, you see a “this will pay off later” mentality.

On the maintenance side of things, you tend to see far less forgiveness.? Certainly, all parties forgive unexpected problems a lot less easily.? They view all of it as a burden.

This difference in attitude translates to the planning as well.? Green field projects justifiably command full time people for the duration of the project.? Maintenance mode tends to get you familiar with the curious term “half of a person.”? By this, I mean you hear things like “we’re done with the Sigma project, but someone needs to keep the lights on.? That’ll be half of Alice.”? The business grudgingly allocates part time duty to maintenance tasks.

Why?? Well, maintenance tends to arise out of reactive scenarios.

Reactive Mode and the Value of Automation

Maintenance mode in software will have some planned activities, particularly if it needs scheduled maintenance.? But most maintenance programmers find themselves in a reactive, “wait and see” kind of situation.? They have little to do on the project in question until an outage happens, someone discovers a bug, or a customer requests a new feature.? Then, they spring into action.

Business folks tend to hate this sort of situation.? After all, you need to plan for this stuff, but you might have someone sitting around doing nothing.? It is from this fundamental conundrum that “half people” and “quarter people” arise.? Maintenance programmers usually have other stuff to juggle along with maintaining “Sigma.”

You should automate this stuff during green field time, when management is willing to invest. If you tell them it means less maintenance cost, they’ll probably bite.

Because of this double duty, the business doubles down on pressure to minimize maintenance.? After all, not only does it create cost, but it takes the people away from other, profit-driven things that they could otherwise do.

So how do we, as programmers, and we, as software shops, best deal with this?? We make maintenance as turnkey as possible by automating as much as possible.? Oh, and you should automate this stuff during green field time, when management is willing to invest.? If you tell them it means less maintenance cost, they’ll probably bite.

Automate the Test Suite

First up for automation candidates, think of the codebase’s test suite.? Hopefully, you’ve followed my advice and built this during green field mode.? But, if not, it’s never too late to start.

Think of how time consuming a job QA has.? If manually running the software and conducting experiments constitutes the entirety of your test strategy, you’ll find yourself hosed at maintenance time.? With “half a person” allocated, no one has time for that.? Without an automated suite, then, testing falls by the wayside, making your changes to a production system even more risky.

You need to automate a robust test suite that lets you know if you have broken anything.? This becomes even more critical when you consider that most maintenance programmers haven’t touched the code they modify in a long time, if ever.

Automate Code Reviews

If I were to pick a one-two punch for code quality, that would involve unit tests and code review.? Therefore, just as you should automate your test suite, you should automate your code review as well.

If you think testing goes by the wayside in an under-staffed, cost-center model, you can forget about peer review altogether.? During the course of my travels, I’ve rarely seen code review continue into maintenance mode, except in regulated industries.

Automated code review tools exist, and they don’t require even “half a person.”? An automated code review tool serves its role without consuming bandwidth.? And, it provides maintenance programmers operating in high risk scenarios with a modicum of comfort and safety net.

Automate Production Monitoring

For my last maintenance mode automation tip of the post, I’ll suggest that you automate production monitoring capabilities.? This covers a fair bit of ground, so I’ll generalize by saying these include anything that keeps your finger on the pulse of your system’s production behavior.

You have logging, no doubt, but do you monitor the logs?? Do you keep track of system outages and system load?? If you roll software to production, do you have a system of checks in place to know if something smells fishy?

You want to make the answer to these questions, “yes.”? And you want to make the answer “yes” without you needing to go in and manually check.? Automate various means of monitoring your production software and providing yourself with alerts.? This will reduced maintenance costs across the board.

Automate Anything You Can

I’ve listed some automation examples that come to mind as the most critical, based on my experience.? But, really, you should automate anything around the maintenance process that you can.

Now, you might think to yourself, “we’re programmers, we should automate everything.”? Well, that subject could make for a whole post in and of itself, but I’ll speak briefly to the distinction.? Build mode usually involves creating something from nothing on a large scale.? While you can automate the scaffolding around this activity, you’ll struggle to automate a significant amount of the process.

But that ratio gets much better during maintenance time.? So the cost center nature of maintenance, combined with the higher possible automation percentage, makes it a rich target.? Indeed, I would argue that strategic automation defines the art of maintenance.

Tools at your disposal

Related resources

eBook – Automated Code Review with CodeIt.Right
eBook – Effective Code Analysis on Legacy Code

Learn more how CodeIt.Right can help you automate code reviews and improve your code quality.

Don’t Just Flag The Issue — Fix It!

October 11, 2016Erik DietrichNo Comments

More years ago than I’d care to admit, I took a software engineering course as part of my graduate CS program.? At the time, I worked a full-time job during the day and did remote classes in the evening.? As a result, I disproportionately valued classes with applicability to my job.? And this class offered plenty of that.

We scratched the surface on such diverse topics as agile methodologies, automated testing, cost of code ownership, and more.? But I found myself perhaps most interested by the dive we did into refactoring.? The idea of reworking the internal structure of code while preserving inputs and outputs is a surprisingly complex one.

Historical Complexity of Refactoring

At the risk of dating myself, I took this course in the fall of 2006.? While automated refactorings in your IDE now seem commonplace, back then, they were hard.? In fact, the professor of the course considered them to be sufficiently difficult as to steer a group of mine away from a project implementing some.? In the world of 2006, I suspect he had the right of it.? We steered clear.

In 2016, implemented automated refactorings still present a challenge.? But modern tool and IDE vendors can stand on the shoulders of giants, so to speak.? Back then?? Not so much.

Refactorings present a unique challenge to tool vendors because of the inherent risk.? They can really screw up users’ code.? If a mistake happens, best case scenario is that the resultant code fails to compile because then, at least, it fails fast.? Worse still is semantically and syntactically correct code that somehow behaves improperly.? In this situation, a refactoring — a safe change to code — becomes a modification to the behavior of production code instead.? Ouch.

On top of the risk, the implementation of refactoring anywhere beyond the trivial involves heady concepts such as abstract syntax trees.? In other words, it’s not for lightweights.? So to recap, refactoring is risky and difficult.? And this is the landscape faced by tool authors.

I Don’t Fix — I Just Flag

If you live in the US, you may have seen a commercial that features a funny quip.? If I’m not mistaken, it advertises for some sort of fraud prevention services.? (Pardon any slight inaccuracies, as I recount this as best I can, from memory.)

In the ad, bank robbers hold a bank hostage in a rather clich?, dramatic scene.? Off to the side, a woman stands near a security guard, asking him why he didn’t do anything to stop it.? “I’m not a robbery prevention service — I’m a robbery monitoring service.? Oh, by the way, there’s a robbery.” (here is a copy of the commercial)

It brings a chuckle, but it also brings an underlying point.? In many situations, monitoring alone can prove woefully ineffective, prompting frustration.? As a former manager and current consultant, I generally advise people that they should only point out problems when they have also prepared proposed solutions.? It can mean the difference between complaining and solving.

So you can imagine and probably share my frustration at tools that just flag problems and leave it to you to investigate further and fix them.? We feel like the woman standing next to the “robbery monitor,” wondering how useful the service is to us.

Levels of Solution

Going back to the subject of software development, we see this dynamic in a number of places.? The compiler, the IDE, productivity add-ins, static analysis tools, and linting utilities all offer us warnings to heed.

Often, that’s all we get.? The utility says, “hey, something is wrong here, but you’re going to have to figure out what.”? I tend to think of that as the basic level of service, or level 0, if you will.

The next level, level 1, involves at least offering some form of next action.? It might be as simple as offering a help file, inline reading, or a link to more information.? Anything above “this is a problem.”

Level 2 ups the ante by offering a recommendation for what to do next.? “You have a dependency cycle.? You should fix this by looking at these three components and removing one mutual dependency.”? It goes beyond giving you a next thing to do and gives you the next thing to do.

Level 3 rounds out the field by actually performing the action for you (following a prompt, of course).? “You’ve accidentally hidden a method on the parent class.? Click here to rename or click here to make parent virtual.”? That’s just an example off the top, of course, but it illustrates the interaction paradigm.? “We’ve noticed a problem, and you can click here to fix it.”

Fixes in Your Tooling

When evaluating your own tools, look to climb as high up this hierarchy as you can.? Favor tools that identify problems, but offer fixes whenever possible.

There are a number of such tools out there, including CodeIt.Right.? Using tools like this is a pleasure because it removes the burden of research and implementation from you.? Well, you can always do the research if you want, but at your own leisure.? But it’s much better to do research at your leisure than when you’re trying to accomplish something else.

The other, important concern here is that you find trusted tooling to help you with this sort of thing.? After all, you don’t want something messing with your source code if it might mess up your source code.? But, assuming you can trust it, this provides an invaluable boost to your effectiveness by automatically resolving your problems and by helping you learn.

In the year 2016, we have far more tooling available, with a far better track record, than we did in 2006.? Leverage it whenever possible so that you can focus on solving the pressing problems of your day to day work.

Tools at your disposal

SubMain offers CodeIt.Right that easily integrates into Visual Studio for flexible and intuitive “We’ve noticed a problem, and you can click here to fix it.” solution.

Learn more how CodeIt.Right can automate your team standards and improve code quality.

The Case for a Team Standard

September 29, 2016Erik DietrichNo Comments

In professional contexts, I think that the word “standard” has two distinct flavors.? So when we talk about a “team standard” or a “coding standard,” the waters muddy a bit.? In this post, I’m going to make the case for a team standard.? But before I do, I think it important to discuss these flavors that I mention.? And keep in mind that we’re not talking dictionary definition as much as the feelings that the word evokes.

blog-case-for-team-standard First, consider standard as “common.”? To understand what I mean, let’s talk cars.? If you go to buy a car, you can have an automatic transmission or a standard transmission.? Standard represents a weird naming choice for this distinction since (1) automatic transmissions dominate (at least in the US) and (2) “manual” or “stick-shift” offer much better descriptions.? But it’s called “standard” because of historical context.? Once upon a time, automatic was a new sort of upgrade, so the existing, default option became boringly known as “standard.”

In contrast, consider standard as “discerning.”? Most commonly you hear this in the context of having standards.? If some leering, creepy person suggested you go out on a date to a fast food restaurant, you might rejoin with, “ugh, no, I have standards.”

Now, take these common contexts for the word to the software team room.? When someone proposes coding standards, the two flavors make themselves plain in the team members’ reactions.? Some like the idea, and think, “it’s important to have standards and take pride in our work.”? Others hear, “check your creativity at the gate, because around here we write standard, default code.”

What I Mean by Standard

Now that I’ve drawn the appropriate distinction, I feel it appropriate to make my case.? When I talk about the importance of a standard, I speak with the second flavor of the word in mind.? I speak about the team looking at its code with a discerning attitude.? Not just any code can make it in here — we have standards.

These can take somewhat fluid forms, and I don’t mean to be prescriptive.? The sorts of standards that I like to see apply to design principles as much as possible and to cosmetic concerns only when they have to.

For example, “all non-GUI code should be test driven” and “methods with more than 20 lines should require a conversation to justify them” represent the sort of standards I like my teams to have.? They say, “we believe in TDD” and “we view long methods as code smells,” respectively.? In a way, they represent the coding ethos of the group.

On the other side of the fence lie prescriptions like, “all class fields shall be prepended with underscores” and “all methods shall be camel case.”? I consider such concerns cosmetic, since they are appearance and not design or runtime behavior.? Cosmetic concerns are not important… unless they are.? If the team struggles to read code and becomes confused because of inconsistency, then such concerns become important.? If the occasional quirk presents no serious readability issues, then prescriptive declarations about it stifle more than they help.

Having standards for your team’s work product does not mean mandating total homogeneity.

Why Have a Standard at All?

Since I’m alluding to the potentially stifling effects of a team standard, you might reasonably ask why we should have them at all.? I can assert that I’m interested in the team being discerning, but is it really just about defining defaults?? Fair enough.? I’ll make my case.

First, consider something that I’ve already mentioned: maintenance.? If the team can easily read code, it can more easily maintain that code.? Logically, then, if the team all writes fairly similar code, they will all have an easier time reading, and thus maintaining that code.? A standard serves to nudge teams in this direction.

Another important benefit of the team standard revolves around the integrity of the work product.? Many team’s standards incorporate methodology for security, error handling, logging, etc.? Thus the established standard arms the team members with ways to ensure that the software behaves properly.

And finally, well-done standards can help less experienced team members learn their craft.? When such people join the team, they tend to look to established folks for guidance.? Sadly, those people often have the most on their plate and the least time.? The standard can thus serve as teacher by proxy, letting everyone know the team’s expectations for good code.

Forget the Conformity (by Automating)

So far, all of my rationale follows a fairly happy path.? Adopt a team standard, and reap the rewards: maintainability, better software, learning for newbies.? But equally important is avoiding the dark side of team standards.? Often this dark side takes the form of nitpicking, micromanagement and other petty bits of nastiness.

Please, please, please remember that a standard should not elevate conformity as a virtue.? It should represent shared values and protection of work product quality.? Therefore, in situations where conformity (uniformity) is justified, you should automate it.? Don’t make your collaborative time about telling people where to put spaces and brackets — program your IDE to do that for you.

Make Justification Part of the Standard

Another critical way to remove the authoritarian vibe from the team standard is one that I rarely see.? And that mystifies me a bit because you can do it so easily.? Simply make sure you justify each item contained in the standard.

“Methods with more than 20 line of code should prompt a conversation,” might find a home in your standard.? But why not make it, “methods with more than 20 lines of code should prompt a conversation because studies have demonstrated that defect rate increases more than linearly with lines of code per method?”? Wow, talk about powerful.

This little addition takes the authoritarian air out of the standard, and it also helps defuse squabbles.? And, best of all, people might just learn something.

If you start doing this, you might also notice that boilerplate items in a lot of team standards become harder to justify.? “Prepend your class fields with m underscore” becomes “prepend your class fields with m underscore because… wait, why do we do that again?”

Prune and Always Improve

When you find yourself trailing off at because, you have a problem.? Something exists in your team standard that you can’t justify.? If no one can justify it, then rip it out.? Seriously, get rid of it.? Having items that no one can justify starts to put you in conformity for the sake of conformity territory.? And that’s when standard goes from “discerning” to “boring.”

Let this philosophy guide your standard in general.? Revisit it frequently, and audit it for valid justifications.? Sometimes justifications will age out of existence or seem lame in retrospect.? When this happens, do not hesitate to revisit, amend, or cull.? The best team standards are neither boring nor static.? The best team standards reflect the evolving, growing philosophy of the team.

Related resources

eBook – Coding Standards in the Real World
eBook – Automated Code Review with CodeIt.Right

Tools at your disposal

Learn more how CodeIt.Right can automate your team standards and improve code quality.