ErikDietrich Archives - Software Quality Blog

CodeIt.Right Rules Explained, Part 17

June 19, 2018Erik Dietrich1

It’s time for a deep dive into yet another three CodeIt.Right rules.? In case you’ve missed it, this continues a post series in which we, well, do a deep dive into the CodeIt.Right Rules.

CodeIt.Right?is an automated code review tool, making it fall under the broad heading of static analyzers.? It checks your source code against a set of rules, both ones that you customize?and a set that comes out of the box.? In this series, we’re focusing on the latter, since those are the ones that will obviously apply to everyone.

Followers of this series will know that I always kick the posts off by listing two static analysis rules of thumb that I advertise as good ideas.

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

If this seems a little obtuse, it’s probably because you could condense these two rules into a single one by logical implication: “always understand a suggested fix.”

But I deliberately choose not to phrase it this way, opting for the two separate rules.? I do this to emphasize your choice: ignore the warning or implement a fix.? If you decide to ignore the warning, you should do so only when you’re fully aware of the risks of doing so.? If, on the other hand, you decide to fix the warning, you should always understand what you’re doing when you change your own code.? Otherwise, you’re programming by coincidence.

Don’t program by coincidence.? Instead, take a look at today’s three rules.

(more…)

CodeIt.Right Rules Explained, Part 16

May 8, 2018Erik Dietrich1

Today, we bring you another post in the CodeIt.Right Rules Explained series.? Up until this point, I’ve been chronicling these posts by their number in the series, but I realize that the numbering: is both academic and relatively easily inferred via the posting category.? Nevertheless, in spite of changing the approach to the title, I’ll recap the premise, as I always do.

CodeIt.Right?is an automated .NET code review tool.? That means that it automatically analyzes your code and applies rules to it.? In the posts in this series, I explain those rules in detail.

In all posts in this series, I start out by listing these rules of thumb for static analysis in the hopes that repetition makes the point.

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

I’ll also explain, as I always do, that I don’t use this phrasing to seem clever or because I can’t figure out the more succinct logical conclusion that these two statements imply: that you should always understand why the tool is suggesting a fix.

I do this because static analyzer warnings present you with a choice: address the warning or ignore it.? And, whichever path you choose, you should do so deliberately and for the right reasons.? Decide to ignore the warning because you think what you’re doing isn’t actually a problem.? Or decide to address the warning because you understand that what you’re doing is problematic and not because you’re programming by coincidence.? Always know what you’re doing.

And with that, let’s dive into today’s rules.

(more…)

5 Ideas for Rules to Add to Your CodeIt.Right Profile

April 24, 2018Erik Dietrich1

A while back, I wrote on the subject of code review horror stories.? This was mostly for fun, but it does speak to an important truth.? Code reviews can be pretty contentious, unpleasant, and even counterproductive when done wrong.

I could spend a bunch of time today talking about how to do them right.? But I won’t.? Instead, I’ll talk about ideas for how to automate your way around possible points of contention.? I’m nothing if not a software developer at heart.

Automated Code Review Goes Beyond the Default Rules

You might be wondering how one “automates around” contentious code reviews.? Perhaps you think I’m proposing some kind of pie-in-the-sky scheme to say, “Alexa, review my code.”? But no.? I’m talking about extending CodeIt.Right’s automated review capabilities.

I have a long-running series on this blog, explaining CodeIt.Right’s automated code review rules.? In those posts, I talk about how you should be very deliberate about either heeding the tool’s advice, or deciding to ignore/deactivate a given rule.

But I never really talk about the idea of adding your own rules.

And that’s what we’re going to do today.? You don’t have to use a tool like CodeIt.Right only for its out of the box capabilities when it offers you a rich customization platform?backed by a fully featured API.? You can write your own rules.

And you?should?write your own rules.? Developers waste an awful lot of time in code reviews endlessly rehashing checks that could be automated easily.? And just because it’s something perhaps more specific to your team that?hasn’t?yet been automated doesn’t mean that you can’t automate it?and pretty easily, at that.

So let’s take a look at five ideas for rules you should add to your CodeIt.Right profile.

(more…)

CodeIt.Right Rules Explained, Part 15

April 3, 2018Erik Dietrich1

It’s time again for another post in the CodeIt.Right Rules Explained series.? We’re fifteen posts deep into the series now, as you can see from the title.? But if you haven’t seen these posts before, I’ll recap the same information I cover in each intro.

CodeIt.Right?is an automated .NET code review tool (both C# and VB), and it has a lot of rules to help you.? In the posts in this series, I explain those rules in detail.

In all posts in this series, I start out by listing these rules of thumb for static analysis in the hopes that repetition hammers them home.

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

And as always, I’ll explain that I don’t use this phrasing to be cute or because I can’t figure out the logical implication of these statements: “always understand why the tool is suggesting a fix.”

I do this because whenever a static analysis tool confronts you with a warning, you face a choice: address the warning or else ignore it.? And, either way, you should act intentionally and for the right reasons.? If you’re ignoring it, do so because you think the pros of your warning-triggering code outweigh the cons implied by the warning.? Don’t ignore it because you don’t understand and don’t feel like doing it.? And on the other side of the coin, don’t change your code simply because some tool tells you to.? Always understand why you’re changing your code, or else you’re programming by coincidence.

All that said, let’s look at today’s three rules.

(more…)

CodeIt.Right Rules Explained, Part 14

March 6, 2018Erik Dietrich1

Today, I’m doing another post in the?CodeIt.Right Rules Explained series.? For anyone who hasn’t seen one of these before, here’s briefly how it works.? CodeIt.Right is an automated .NET code review tool, and it has a lot of rules to help you.? In the posts in this series, I explain those rules in detail.

Whenever I post in this series, I start with my two rules of thumb for static analysis.

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

As always, I’ll explain that I don’t phrase it this way because I think I’m clever.? I could just say, “Figure out why the tool is suggesting this.”? But I specifically opt not to.

The reason I do this is that whenever the tool confronts you with a warning, you have a choice: address the warning or ignore it.? And in either case, you should make your choice for the right reasons.? Are you ignoring it because you’ve determined that the pros of having it outweigh the cons the tool is warning you about?? Or are you ignoring it because you don’t feel like dealing with it?? The same thing also applies on the side of implementing fixes.

So, that said, let’s look at today’s three rules.

(more…)

Is Visual Basic Dead?

February 27, 2018Erik Dietrich13

Is Visual Basic dead?? Yup.? Wow, hey, that might have been the easiest blog post I’ve ever written.? See ya next week!

Oh, wait.? You probably want me to justify this claim somehow, don’t you?? And then you probably want me to add support for the argument, nuance in position, and something actionable.? Alright, fine.? Have it your way.

Is Visual Basic Dead?? Let’s Define Dead: Zombies and Nothingness

First, the nuance.? To continue with the dead metaphor, let’s consider two subtly different flavors of dead:

First, you have truly dead languages, fading into nothingness and complete obscurity.? Think, for instance, of Pascal, which has plummeted on the TIOBE index from a peak of third most popular to today’s position of 136th, putting it behind every language you’ve ever heard of and 50 you haven’t.
Then you have zombie languages.? Zombie languages die out of the realm of first-class, maintained languages but refuse to stop running the software of the world.? I’m looking at you, COBOL.

What determines whether a language rests quietly in its grave or goes lurching around the countryside, terrorizing companies with legacy applications in their portfolio?? Well, obviously there are countless factors involved.? But I’d argue that the languages most likely to zombify are the ones that enjoyed the most prolific adoption within the risk-averse, cost-conscious enterprise.? For instance, the worlds of government and banking have no shortage of green screens and mainframe applications?upon which they rely to this day.

So is Visual Basic dead?? Again, yup.? But I would argue that it’s a zombie language rather than a language fading to nothingness.? As an industry, we collectively rapid-prototyped a lot of WinForms and VBA things into existence, many of which keep chugging along to this day.

But, But, But…

I’ve introduced nuance but not really any reasoning or evidence so far.? And I can imagine some objections to what I’m saying.

(more…)

Can We Retire the Design Document, Already?

February 13, 2018Erik DietrichNo Comments

In the interest of running a social experiment to amuse myself, I won’t do a Google search for the term design document.? I could easily do this, but I won’t.? Instead, I’m going to hazard a guess as to what the search would yield: a Wikipedia article and a bunch of really old web pages that use the passive voice a lot.

I say this because design documents, like the singleton design pattern and systems such as?Hungarian notation, were legitimately good-seeming ideas that just landed on the wrong side of history.? (And like those two things, I’m sure someone will come storming straight out of 1998 and into the comments section below, telling me that I’m a horrible human being for claiming this.? “It says it’s a good idea in a book, Erik, you imbecile, which you’d know if you could?read!“? But I digress.)

The design document captures design intent.? It helps junior developers work with less supervision.? It paves the way for maintenance programmers to know what happens.? And it even communicates technical concepts to non-technical stakeholders.? That’s a lot of nice wins for one modest four-page MS Word document.? How can I possibly claim we should retire the design document?

Well, here’s the thing.? I’m not saying a design document provides no benefits.? I’m saying that, when compared to?other options, a design document does a less efficient job at providing every benefit that it offers.? Oh, and it comes with significant downsides.? So let’s look at those downsides and then at more efficient ways to realize its benefits.

Design Document as Part of a Failed Metaphor

In 1970, a gentleman named Winston Royce wrote one of the most ironically misunderstood articles you’ll ever find.? He drew a now-iconic picture of software as a series of rigidly delineated phases that resembled a waterfall, and described it as a “flawed, non-working model.”? But, oops.? The industry at large said, “You had me at waterfall,” and by 1985, the US Department of Defense had immortalized these rigid phases?into their standard for working with software development contractors.

This idea of software development tracked neatly with construction and manufacturing.? Spec out what people need, draw up an elaborate blueprint of every last detail, have the working grunts construct it, then send in the quality people.? ?So much did we like this metaphor that our job titles track closely with these disciplines (architect and engineer)—except when you stop and think about it, building construction actually makes an apt metaphor for terrible software: rigid, massively expensive to change, and completely interdependent.

The design document hails from a different time—a different world.? It makes sense in a world where the following things are true:

Software happens in two phases: architects think and plan, and grunts code up their vision without hurting their brains very much.
Design documents inform code, but the reality of code doesn’t inform design documents.
You can control scope enough to make design document creation not wasteful/prohibitively expensive.
The most faithful way to generate representations of a codebase/architecture are manual diagrams and typed explanations.

But we don’t live in this world.

(more…)

CodeIt.Right Rules Explained 13 includes

CodeIt.Right Rules Explained, Part 13

January 30, 2018Erik Dietrich1

It’s time for another post in the CodeIt.Right Rules Explained series.? If this is the first such post you’ve seen, I’ll explain briefly how it works.? CodeIt.Right is an automated code review tool for .NET, and it has a bunch of rules.? In these posts, I explain those rules in detail.

Whenever I post in this series, I start with my two rules of thumb for static analysis.

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

As always, I’ll explain that I don’t phrase it this way to be cute.? You could reduce this logically to “figure out why the tool is suggesting this.”? But I specifically opt not to.

The reason is that each time the tool confronts you with a warning, you have a choice: address the warning or ignore it.? And in either case, you should make that choice for the right reasons.? Are you ignoring it because you’ve determined that the pros of having it outweigh the cons the tool is warning you about?? Or are you ignoring it because you don’t feel like dealing with it?? The same thing applies, too, on the side of implementing fixes.

So, that said, let’s dive into three more rules today.

(more…)

How Do You Evaluate Code Readability?

January 23, 2018Erik Dietrich2

Evaluating code readability is actually pretty easy.? I’ll explain it in a way that you can easily illustrate with a flow diagram.? And you can see if you agree with my assessment.

Did someone else write this code?? If so, it’s not readable.
Did I write this code but more than six months ago?? If so, it’s not readable.
Otherwise, it’s readable.

Sound about right?

I kid, but only kind of.? This tends to be my visceral, subconscious reaction before I reign myself in and think rationally.? And I bet the same is true for a lot of you reading as well.

Code Readability and Subjectivity: the Elephant in the Room

This happens because of the inherent subjectivity involved with the idea of code readability—or, more specifically, with the idea of readability in general.

To understand what I mean, let’s use an extreme to make a point.? I could write a few lines of C# that just about any programmer reading would understand at a glance.? But a non-programmer or neophyte programmer might read it and fail to grasp even these basics.

“What does ‘return’ mean?”

So readability depends on your prior knowledge and your perspective.? And frankly, it also depends a lot on your own preferences.? Some folks seem to like compact, dense code while others favor frequent empty lines to “space things out.”

What does all of this add up to?? Well, it means that we cannot possibly tackle this subject without acknowledging the opinion-based and subjective nature of it.? But that doesn’t mean we shouldn’t address it.

A Loose Framework for Discussing Code Readability

I’m going to spend the rest of the post offering my opinion on how you can make your code more readable.? But before I do that, let’s reframe slightly.? Let’s think of code readability as time to comprehend.

Of course, time to comprehend doesn’t eliminate subjectivity.? But it does introduce a measurable concern that we can use as a metric.? So, for the rest of this post, I’ll talk about code readability in terms of time to comprehend, with the following guidelines:

We’re talking about time to comprehend for a developer in the language of average experience.
Matters of preference and familiarity will affect this time to an extent, but so will various language properties.
Code readability is generally preferable, but not in all cases (e.g., you might have need to optimize a critical path where advanced language usage and other concerns trump readability).

Now, all of this is still my opinion about code readability.? You’ll have your own opinions, of course.? But it’s through this lens I offer you the following tips on how you might evaluate and improve code readability.

(more…)

CodeIt.Right Rules Explained, Part 12

November 28, 2017Erik Dietrich1

This week, we bring you another post in the CodeIt.Right Rules Explained series.? In case this is new for you, with each post in the series, I take you through three CodeIt.Right?rules in detail.? CodeIt.Right is an automated code review tool, making use of static code analysis.

As I always do with these posts, I’ll start with two solid rules of thumb for static analysis.

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

And, as I always do, I’ll explain that I don’t phrase it this way to play some sort of game.? You might wonder why I don’t just tell you to learn every suggested fix and call it a day.

Well, I phrase it this way to make it clear that you face a specific choice each and every time you encounter an analysis warning: fix it or ignore it.? And when you make that choice, you should make it for the right reasons.? “I don’t know what this means,” isn’t the right reason.? I also approach it this way because trying to learn?all?of the rules at once would prove extremely daunting.

So let’s dive deep into understanding another three rules today.

(more…)