ErikDietrich Archives - Page 3 of 7 - Software Quality Blog

Anatomy of C# Spell Check

August 22, 2017Erik DietrichNo Comments

With the vast ecosystem of tools and plugins around Visual Studio, the existence of a C# spell check shouldn’t come as a surprise. ?But maybe it does. ?It’s entirely possible that this sort of spell checking never occurred to you as something worth doing. ?Or maybe it just never occurred to you at all.

Personally, I think spell checking your code is most definitely worth doing. ?I won’t belabor the point here, since I’ve made this case in the past. ?Suffice it to say that since you can have it so effortlessly, you might as well get your spelling right.

Today, I’d like to talk instead about the problem of a C# spell checker (or a general purpose spell checker to use inside an IDE). ?In order to make things easy on you, the spell checker has to do some pretty sophisticated stuff and wrestle with subtle problems.

Spell check in a word processor is relatively easy from an implementation perspective. ?You assume the person is typing natural language and check all words against a dictionary. ?But in code? ?Not so much. ?Let’s take a look at some of the reasons for that.

C# Spell Check: the Basic Challenge

Written English (or any natural language) has very specific rules around spelling and grammar. ?Spaces demarcate words, and periods do the same for sentences. ?If you spell words incorrectly or have sentence fragments, you have nonsense, as far as the language is concerned.

This is, of course, also true of source code. ?Spaces separate tokens, and semicolons (or parentheses) demarcate statements. ?But whereas precision around English syntax and semantics optimizes for human understanding, these properties in code optimize for compiler understanding. ?You have to spell and case reserved keywords correctly so that the compiler can identify them. ?But non-reserved language tokens? ?The compiler has no opinion or preference.

This creates a rule vacuum of sorts. ?As I type this sentence, English rules dictate that I capitalize the word “English.” ?If I wrote a method named GetEnglishEquivalent, the compiler would care not a whit whether I capitalized any or all of those letters. ?We programmers are left to figure this out by convention.

So the core challenge of C# spell check is to join these two worlds and navigate the subtleties of rules versus conventions.

(more…)

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…)

Automated code review is going to be worth the time.

Are You Aggressively Trying for Automated Code Review?

August 3, 2017Erik Dietrich1

Not surprisingly, software development teams have a propensity to automate. ?After all, most of what we do involves automating formerly manual processes. ?Stop keying that data in by hand! ?Let’s write a script that loads it automatically.

As software developers, we thus become connoisseurs of automation opportunity. ?Come on. ?Tell me you’ve never wandered around your office, observing others’ inefficient workflows. ?If you didn’t have a ton of things to do, you’d write a shell script that blew their minds. ?They’d have so much free time on their hands that they could take up knitting for part of the day.

But typically you don’t do things like this. ?You have more important things to do, like build software for your customers. ?And this hints at an intuitive sense of priority among software groups. ?You understand that you could?automate all sorts of things but that you only?should automate certain things. ?Adding a critical feature to the software you sell takes priority over automating George’s weekly email about fantasy football.

At least, that works for everyone else. ?And yet we have a surprising blind spot when it comes to ourselves. ?In some cases, we quixotically look to automate everything we might ever possibly do more than once. ?XKCD once captured this nicely. ?And then, on the flip side, we sometimes fail to recognize things in our own workflow that we could and should automate.

Code review definitely qualifies in this latter category. ?We seem to think of it as inherently manual activity, often ignoring the possibly of automated code review.

Aggressively Seeking Automated Code Review

In the title of the post, I mention?aggressively pursuing automated code review strategies. ?Bear in mind that aggressive does not mean reckless, nor does it mean automating without considering ROI. ?You don’t want to fall on the wrong side of that XKCD chart.

I’m talking instead about aggressiveness in auditing your activities for automation opportunities. ?Any time you spend on manual activities is time that could theoretically be automated. ?Are you critically examining all of that time, or do you have activities that you assume must happen manually?

When I talk about aggressiveness, I’m talking about considering nothing in your manual process as sacred. ?You should keep your eyes open for tools or techniques that can save you time, making your manual reviews more critical and your process more efficient. ?Let’s talk about some examples of those opportunities.

(more…)

When looking for the concept of Microsoft HTML Help, it can be hard to even know what to Google.

Upgrading from Microsoft HTML Help

August 1, 2017Erik DietrichNo Comments

Before I get into talking about Microsoft HTML Help or any alternatives, let me ask you something. ?Have you ever had the singularly frustrating experience of staring blankly at the Google homepage? ?You’re staring blankly because it occurs to you that you don’t even know what words to type.

Maybe this happens because you’re searching for a name that muddies the waters. ?Someone creates a new JavaScript framework named Taylor Swift. ?Or perhaps it happens because you know only vaguely how to describe the concept. ?Try buying a replacement cotter pin?if you don’t actually know the name of the thing. ?You start googling things like “that thing that stops a trailer hitch from falling off my car.” ?And of course, that doesn’t work. ?So you stare blankly, frustrated.

Microsoft HTML Help…or Whatever

Microsoft HTML Help is one of those hard-to-google things, based on my observations. ?Or should I call it Microsoft Help? ?Or maybe “that thing when you hit F1 in Windows and a window pops up”? ?You get the idea.

I’ve seen people to struggle when it comes to articulating this concept. ?Beyond the word “help,” which resides at the center, the rest is a little mysterious. ?And by and large, the world doesn’t care to name it. ?They hit F1 or click for help, and, voil?, help appears in the form of a window. ?What’s to search?

But if you’re making a software product, you might think, “Hey, I want to make a ‘help’!” ?That’s when you’re going to start googling, and that’s when things get weird.

Let’s say you google “create a windows help.”? You get an ad that you obviously skip, and then you have something about creating a help “project” and something about Microsoft HTML Help. ?But you don’t want to create a project or HTML — you want to create a Windows help thingy. ?The next link, “Create a Help Project (Windows),” sounds promising. ?But alas, it just describes things in vague terms, including “create a help project” as well as compiling and testing help…or something.

Ugh. ?This search and others like it invite frantic and frustrated clicking. ?And they do this because sources speaking to the problem assume that you already know how this help thing works.

(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…)

.NET Code Documentation So Easy It’s an Afterthought

July 20, 2017Erik Dietrich5

Though I’ll talk today about .NET code documentation, I want to start further back than that. And by “that,” I mean further back than .NET. I realize that may date me somewhat, but please bear with me.

Most things in the programming world date back further than you’d think. For a dramatic example of this, consider functional programming. All the rage today, it actually dates back to the 60s in practice and 30s in theory. Speculating about the reason for temporal myopia would go beyond the scope of this post, but understand that this tendency toward myopia does exist.

With that in mind, let’s talk about some GUI builders.

A Tale of Two GUI Builders

Now we get to the part that predates .NET. I’m going to reach back into my early career and compare my relatively simultaneous experience with two GUI building technologies.

First, I encountered Swing, a Java GUI toolkit. While Swing did not include a GUI builder at the time, my project packaged it with one. I cannot remember its name for the life of me, but this thing was a train wreck. Moving controls around on a form caused the spewing of improbable amounts of code into my Java classes. Attaching handlers to GUI events only half worked, requiring wire up by hand. I had such struggles with it that I gave up and just hand-coded everything in Java.

Shortly after working on that project, I found myself saddled with a VB6 application. At the time, .NET actually existed, but nobody had ported this thing to it. So I used VB6. And I?loved it.

That probably sounds as weird to hear as it feels to type, but there it is. Compared to my experience with Swing and its nightmarish GUI builder, this was a refreshing summer breeze. I could move controls around to my heart’s content, wire up events easily, and get stuff done.

(more…)

Documentation Tools for Programmers

July 19, 2017Erik Dietrich1

More than a decade ago, I worked somewhere that would ship CDs containing commercial software. ?Along with others, I’d program applications that ran commercial mail sorting machines and provided a user interface for the operators. ?To update or patch the software, we’d cut official CDs and send them out in the mail.

These CDs would, obviously, contain the software. ?But they’d also contain a rather elaborate PDF of the user’s manual. ?In some cases, we might mail them a physical user’s manual. ?And that manual was a formidable, polished document.

You’re probably expecting me to complain about writing that document. ?But I won’t do that because I never had a hand in writing it at all. ?Back then, we had a professional tech writer on staff that handled all manuals and end user documentation. ?At most, I would interact with this person when he’d shoot me the occasional email, asking how something worked.

If you were to ask me about documentation tools back then, I’d have looked at you strangely. ?I dunno. ?Ask the tech writer.

Documentation Tools Today Run the Gamut

Today we have a much different landscape. ?Between the rise of agile methodologies, ease of software delivery, cost savings, and automation, I suspect very few organizations hire tech writers to draw up user manuals for their products. ?That’s probably gone the way of the installation CD.

And today you probably have to help out when it comes to documentation. ?That means you need to leverage some documentation tools — at least if you want to avoid serious boredom.

Also complicating matters is the fact that modern documentation takes many forms and has many audiences. ?Gone are the days of only CD user manuals and man pages. ?So I’ll talk today about documentation tools, but I’ll divide the discussion up by audience and purpose.

(more…)

CodeIt.Right Rules Explained, Part 7

July 13, 2017Erik Dietrich1

Today, I’ll do another installment of the CodeIt.Right Rules, Explained series.? This is post number seven in the 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 like rhetorical cuteness.? After all, I could simply say, “Learn the reasoning behind all suggested fixes.”? But I want to highlight the decision you face when confronted with static analysis feedback.? In all cases, you must actively choose to ignore the feedback or address it.? And for both options, you need to understand the logic behind the suggestion.

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

(more…)