TeamStandard Archives - Software Quality Blog

Writing that says "rules, you must, you must not"

Using CodeIt.Right to Create C# Coding Standards

June 5, 2018Carlos SchultsNo Comments

Does your team use a coding standard? If the answer is no, then I?m afraid you?re missing out on a lot of important benefits.?This post will help you create (and automate) C# coding standards using Submain?s CodeIt.Right.?I?ll start out by making the case that you need a coding standard. We here at the SubMain blog have already covered that subject, of course, but I?ll revisit it anyway.

With that out of the way, I?ll go on to explain the most common problems that occur when teams try to implement coding standards and code reviews manually.

Finally, I?ll show you how automation can heal these pains, and how to use CodeIt.Right for doing so.?Let?s get started. (more…)

In today's post on hungarian notation, we look at why it wound up looking like this toe-tagged body at the morgue.

Hungarian Notation Postmortem: What Went Wrong?

December 12, 2017Rick Beley27

Is Hungarian notation really adjDead? Suggesting a postmortem might be a bit premature, but it could be fun to take a quick dive into what we?ve learned from a really smart Hungarian named Charles Simonyi who tried to find a better way. Anyone who tries to bring some clarity to the chaos they find in their everyday dealings has a lot in common with us developers. Mr. Simonyi is one of us. Let?s hear him out!

What Is Hungarian Notation?

Hungarian notation is one of those topics of great debate in the programming community. You can find just as many intelligent and well-respected proponents as you can find opponents. Likewise, you can find lists about its positive contributions, and you can read articles on why it should never surface. As with most of these more philosophical debates, I find myself stuck in the middle. And when that happens, I find great value in hearing out those with strong opinions about it.

To a non-developer, computer code can appear rather ambiguous and obscure. To a developer, someone else?s computer code can be the same when we fail to be united in our approach. If you?ve spent any amount of time hacking away at a keyboard, writing complex computer instructions, I?m sure you?ll understand the concepts behind Hungarian notation. Mr. Simonyi is simply trying to bring some clarity to the language you?re using with your computer.

How Does It Work?

So, what is Hungarian notation and how does it work? To sum it up, Hungarian notation is a systematic approach to naming variables in our programs, using the type and a given name, in that order. If ?lastName? is a string, think strLastname for its Hungarian notation. Consider this block of pseudocode:

string ln= ?Simonyi?;
string fn= ?Charles?;
string dn= ln + ?,? + fn;
int len = dn.length();

It?s a pretty simple piece of code with a few string variables and an integer. Come on a quick journey with me; let’s say this was line 444 through 448 in 1000+ lines of code. The variable names tell us very little about what we?re storing in them. And when the variable is referenced further down in the code, we may find ourselves scrolling back up to find out what it means. If we used Hungarian notation, along with some better variable names, maybe we?d see something like this:

string sLastname = ?Simonyi?;
string sFirstname = ?Charles?;
string sDisplayname = sLastname + ?,? + sFirstname;
int nLength= sDisplayname .length();

You?ll notice right away that the variable names are clear, their intents and purposes are solidified, and they?re prepended with the correct type (s for string, n for integer). No more guessing, and no more scrolling back to check the type.

That?s it.

Yup, that?s the basic idea behind Hungarian notation. And you can find article after article, opinion piece after opinion piece, and plenty debate all throughout the internets about it.

(more…)

An entire large team arguing over the coding standard.

What’s Your Worst Experience with a Coding Standard?

November 7, 2017Erik Dietrich9

I remember the first time I encountered GhostDoc.? It was an oasis in a professional desert of soul-sucking conformity.

Okay, wait. Let me back up and explain.

I was working in a custom app dev shop at the time.? While working there, I worked on an assortment of apps, big and small, and I delivered to an assortment?of clients, big and small.? Some had their own internal maintenance devs, and some did not.? And yet, in spite of this disjoint, hodgepodge arrangement, the company maintained a single?and relatively?involved coding standard for dozens of folks on dozens of projects.

The “Professional” Coding Standard

Most aspects of the standard were unremarkable and understandable.? So, on the whole, this didn’t bother me.? But there was an edict floating around in there that said every method and class, no matter what, needed XML doc comments.

This applied to code being maintained by client developers and to code that nobody would ever look at again.? It applied to both API deliverables and to GUI crud apps that nobody would touch again.? Why comment everything in this fashion, no matter what?? Because it makes us “look professional,” that’s why.

Ugh.

And so I found myself laboriously going back and brainlessly adding comments to dozens of files.? You see, I hadn’t known about this standard when I started, so I didn’t bother commenting this forms-over-data thing for which we weren’t even delivering source code.? So I had a lot of “work” to do.

Initially, I contemplated writing my own commenting engine.? I honestly think I could have done that in less time than it would take to hand comment.? But then I figured something like this had to exist already, and my search led me quickly to GhostDoc.

Once I discovered that, I sprayed my code with comments like an exterminator taking care of an ant problem.? Then I called it a day.

As I’ve discussed previously, this is NOT how I’d use GhostDoc today or how I’d approach commenting in general.? But it got the “job” done, and the powers that be considered “my” comments completely acceptable.? Project finished.

(more…)

When is It Okay to Turn off Static Analysis Guidance

October 20, 2016Erik DietrichNo Comments

The balance among types of feedback drives some weird interpersonal dynamics and balances.? For instance, consider the rather trite (if effective) management technique of the “compliment sandwich.”? Managers with a negative piece of feedback precede and follow that feedback with compliments.? In that fashion, the compliments form the “bun.”

Different people and different groups have their preferences for how to handle this.? While some might bend over backward for diplomacy others prefer environments where people hurl snipes at one another and simply consider it “passionate debate.”? I have no interest arguing for any particular approach — only in pointing out the variety.? As it turns out, we humans find this subject thorny.

To some extent, this complicated situation extends beyond human boundaries and into automated systems.? While we might not take quite the same umbrage as we would with humans, we still get frustrated.? If you doubt this, I challenge you to tell me that you have never yelled at a compiler because you were sure your code had no errors.? I thought so.

So from this perspective, I can understand the frustration with static analysis feedback.? Often, when you decide to enable a new static analysis engine or linting tool on a codebase, the feedback overwhelms.? 28,326 issues the code can demoralize anyone.? And so the temptation emerges to recoil from this feedback and turn off the tool.

But should you do this?? I would argue that usually, you should not.? But situations do exist when disabling a static analyzer makes sense.? Today, I’ll walk through some examples of times you might suppress such a warning.

False Positives

For the first example, I’ll present something of a no-brainer.? However, I will also present a caveat to balance things.

If your static analysis tool presents you with a false positive, then you should suppress that instance of the false positive.? (No sense throwing the baby out with the bathwater and suppressing the entire rule).? Assuming that you have a true false positive, the analysis warning simply constitutes noise and not signal.? Get rid of it.

That being said, take care with labeling warnings as false positives.? False positive means that the tool has indicated a problem and a potential error and gotten it wrong.? False positive does not mean that you disagree with the warning or don’t care.? The tool’s wrongness is a good reason to suppress — you not liking its prognosis false short of that.

Non-Applicable Code

For the second kind of instance, I’ll use the term “non-applicable code.”? This describes code for which you have no interest in static analysis warnings.? While this may sound contradictory to the last point, it differs subtly.

You do not control all code in your codebase, and not all code demands the same level of scrutiny about the same concepts.? For example, do you have code in your codebase driven by a framework?? Many frameworks force some sort of inheritance scheme on you or the implementation of an interface.? If the name of a method on a third party interface violates a naming convention, you need not be dinged by your tool for simply implementing it.

In general, you’ll find warnings that do not universally apply.? Test projects differ from your production code.? GUI projects differ from data access layer ones.? And NuGet packages or generated code remain entirely outside of your control.? Assuming the decision to use these things happened in the past, turning off the analysis warnings makes sense.

Cosmetic Code Counter to Your Team’s Standard

So far, I’ve talked about the tool making a mistake and the tool getting things right on the wrong code.? This third case presents a thematically similar consideration.? Instead of a mistake or misapplication, though, this involves a misfit.

Many tools out there offer purely cosmetic concerns.? They’ll flag field variables not prepended with underscores or methods with camel casing instead of Pascal casing.? Assuming those jive with your team’s standards, you have no issues.? But if they don’t, you have two options: change the tool or change your standard.? Generally speaking, you probably want to err on the side of complying with broad standards.? But if your team is set with your standard, then turn off those warnings or configure the tool.

When You’re Buried in Warnings

Speaking of warnings, I’ll offer another point that relates to them, but with an entirely different theme.? When your team is buried in warnings, you need to take action.

Before I talk about turning off warnings, however, consider fixing them en masse.? It may seem daunting, but I suspect that you might find yourself surprised at how quickly you can wrangle a manageable number.

However, if this proves too difficult or time-consuming, consider force ranking the warnings, and (temporarily) turning off all except the top, say, 200.? Make it part of your team’s work to eliminate those, and then enable the next 200.? Keep at it until you eliminate the warnings.? And remember, in this case, you’re disabling warnings only temporarily.? Don’t forget about them.

When You Have an Intelligent Disagreement

Last up comes the most perilous reason for turning off static analysis warnings.? This one also happens to occur most frequently, in my experience.? People turn them off because they know better than the static analysis tool.

Let’s stop for a moment and contemplate this.? Teams of workaday developers out there tend to blithely conclude that they know their business.? In fact, they know their business better than people whose job it is to write static analysis tools that generate these warnings.? Really?? Do you like those odds?

Below the surface, disagreement with the tool often masks resentment at being called “wrong” or “non-compliant.”? Turning the warnings off thus becomes a matter of pride or mild laziness.? Don’t go this route.

If you want to ignore warnings because you believe them to be wrong, do research first.? Only allow yourself to turn off warnings when you have a reasoned, intelligent, research-supported argument as to why you should do so.

When in Doubt, Leave ’em On

In this post, I have gingerly walked through scenarios in which you may want to turn off static analysis warnings and guidance.? For me, this exercise produces some discomfort because I rarely find this advisable.? My default instinct is thus not to encourage such behavior.

That said, I cannot deny that you will encounter instances where this makes sense.? But whatever you do, avoid letting this become common or, worse, your default.? If you have the slightest bit of doubt, leave them on.?? Put your trust in the vendors of these tools — they know their business.? And steering you in bad directions is bad for business.

Learn more how CodeIt.Right can automate your team standards, makes it easy to ignore specific guidance violations and keep track of them.

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

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.

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