SubMain.com
YouTube
RSS

CodeQuality

Home Category: CodeQuality (Page 3)
CodeItRightRules14

CodeIt.Right Rules Explained, Part 14

Erik Dietrich1 Comment

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

CodeIt.Right Rules Explained 13 includes

CodeIt.Right Rules Explained, Part 13

Erik Dietrich1 Comment

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

Code Monkey Computing Readability

How Do You Evaluate Code Readability?

Erik Dietrich2 Comments

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.

  1. Did someone else write this code?? If so, it’s not readable.
  2. Did I write this code but more than six months ago?? If so, it’s not readable.
  3. 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:

  1. We’re talking about time to comprehend for a developer in the language of average experience.
  2. Matters of preference and familiarity will affect this time to an extent, but so will various language properties.
  3. 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…)

White Rabbit is Late

Coding Best Practices When You’re Short On Time

Carlos SchultsNo Comments

One topic in software development that really fascinates me is coding best practices. I’m always searching for ways to improve my work and deliver value in a fast and consistent manner.

It can be tricky to define what a “coding best practice” is. Some people are even in favor of downright retiring the term!?But one thing pretty much everyone agrees upon is this: coming up with and implementing strategies—by whatever name you call them—to improve the output of one’s work is something that any developer worth his or her salt should be continuously doing.

Of course, there’s no free lunch. The adoption of a best practice takes time…and sometimes you just don’t have much of that to begin with. And then there’s management, whose buy-in is not always guaranteed.

So, what to do if your development team is struggling with the poor quality of a codebase while lacking time to implement best practices that would help?

The answer I offer you today is what I’ll call the “coding best practices emergency pack”: a small list of coding best practices that you can adopt on relatively short notice to get your team and your codebase from utter chaos to a more manageable?state.

Because there’s lots of advice on coding best practices out there, to the point where it’s hard not to feel overwhelmed, I narrowed down my list of emergency-pack best practices by requiring they meet three criteria:

  • They must be fundamental, in the sense that they’re the building blocks with which you can implement more sophisticated practices later.
  • You can adopt them in relatively short notice. (I’d say a week is feasible.)
  • Their cost is free or very low.

The practices that follow all fit these parameters. And without further ado, here it is: my coding best practices emergency pack, with items listed in the order they should be implemented and starting with the most critical one.

(more…)

4 Common Datetime Mistakes in C# And How to Avoid Them

Carlos Schults12 Comments

Do you remember the “falsehoods programmers believe about X” meme that became popular among software blogs a few years ago? The first one was about names, but several others soon followed, covering topics such as addresses, geography, and online shopping.

My favorite was the one about time. I hadn’t thought deeply about time and its intricacies up until that point, and I was intrigued by how a fundamental domain could be such a fertile ground for misunderstandings.

C# Datetime Stamps

Now even though I like the post, I have a problem with it: it lists wrong assumptions, and then it basically stops there. The reader is likely to leave the article wondering

  • Why are these assumptions falsehoods?
  • How likely is it that I’ll get in trouble due to one of these assumptions?
  • What’s the proper way of dealing with these issues?

The article is interesting food for thought, but I think it’d make sense to provide more actionable information.

That’s what today’s post is about. I’m going to show you four common mistakes C#/.NET developers make when dealing with time. And that’s not all. I’ll also show what you should do to avoid them and make your code safer and easier to reason about.
(more…)

Code review vs pair programming (as shown here): which should your team pick?

Code Review vs Pair-Programming: Which One Should Your Team Pick?

Carlos Schults3 Comments

Some weeks ago, I was browsing Twitter when I saw this:

This prompted a brief discussion between the author and me. He made good arguments, but I left unconvinced that pair programming was the obvious winner.

As someone who?s implemented code review with success and also paired to some extent, I could see how both practices can be valuable.?But is one of them clearly better than the other? Are code review and pair programming interchangeable, or are there scenarios in which one clearly shines?

That?s what I?m going to answer today. Let?s dive in.

(more…)

Too much commented out code in your codebase will have you pulling your hair out, like this poor guy.

Commented Out Code Is Junk In Your Codebase

Peter Morlion3 Comments

Why do we have the tendency to comment out code instead of just deleting it? The reason is that we don?t want to lose a piece of code that might come in handy in the future. Maybe we think we?re still going to need it because it solves some problem in an elegant way. Or maybe it?s because it helps us when debugging.

It all boils down to fear of losing information. But commented out code will get in the way more than it will help you, and it’s better off being deleted. I?ll expand on why below and provide some possible alternatives.

Why Commented Out Code Is a Problem

1. It Distracts

At the very least, commented out code will distract you and your team members from the actual code. It?s tempting to think our brains can filter out the commented blocks or that just a few lines won?t make our minds wander. But in reality, the commented out code is just an extra hurdle your brain needs to jump when trying to make a mental model of what the code is doing. And that by itself is hard enough, even in very clean codebases.

2. It’s a Source of Code Rot

More often than not, commented out code will start to ?rot.? The longer code stays commented out, the higher the chances it no longer fits when uncommented.

One possibility is that it just doesn?t compile anymore. The codebase will likely have changed, and the live code will have evolved with it. But the commented out code will still be as it was when you put it in comments.

A more dangerous situation could arise if the code does compile but the behavior of any underlying code is altered. The commented out code may make calls to other components whose behavior has changed. This means the commented out code no longer does exactly what it was intended to do. That’s a potentially be a dangerous problem, and it means you’ll be wasting your time trying to find the cause of an obscure bug. In both cases, it?s a risk to the team and the company, and one that could have been avoided.

Finally, the commented out code may have been a good idea at the time, but fast forward several months or years and you can probably come up with a better solution. Languages, frameworks, and techniques evolve, and in time you will have acquired more knowledge, causing you to solve a problem in a different way. Trust your future self to solve the problem that the commented out code solved.

So how can we avoid the problems caused by commented out code without losing our piece of code forever?

(more…)

CodeIt.Right Rules Explained, Part 12

CodeIt.Right Rules Explained, Part 12

Erik Dietrich1 Comment

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

CodeIt.Right Rules Explained, Part 11

Erik DietrichNo Comments

It’s time for another post in the CodeIt.Right Rules Explained series.? I daresay it’s becoming a pretty predictable post series, with a pretty predictable cadence.? And that’s a good thing!? CodeIt.Right offers automated code review, and this series of blog posts gives you a detailed tour of the what and also the why of the code review rules.

As has become custom, 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.

Every month, I explain that I don’t phrase it this way to play some sort of game.? After all, I could just declare that everyone should learn every suggested rule and be done with it.? But 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.

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

(more…)

You don't need a code review template like the one shown here.

You Don?t Need a Code Review Template

Erik Dietrich1 Comment

What do you have in mind when you search or hope for a code review template?? I’ll bet I can guess.

You’re looking for something to guide you through the process.? In your mind, this probably takes the form of a worksheet of some kind.? The appropriate document should have a checklist of items for you to tick off and perhaps some free-form text spaces for you to make notes.? It will also guide you through the process in general.

I get it.? But you really don’t need this, even though it seems perfectly reasonable and inviting.

The Actual Life of a Code Review Template

Before I dive into the meat of?why you don’t need this document, let me talk about what will happen to it when you acquire it.

First, you’ll go searching and find something like this.? Then you’ll find a few more of those and put it together into your own list.? It will include items like the following:

  • Each method should have a clear responsibility.
  • Each method should also have no more than three parameters.
  • Close any connections you open and dispose of any resources that need disposing.

And so on.

You’ll put this document together, and then you’ll stick it on your group’s SharePoint site, where everyone can see it and add to it if need be.? “It’s a living document,” you’ll assure everyone.

Your brand-new code review process will get off to a good start, with people participating and faithfully following the code review template.? They’ll check the checkboxes, fill out the text for the questions, and generate adjustments to the code where needed.? For a while, anyway.

But where you’d eventually expect the efficiency of these reviews to improve, the opposite happens.? The document grows. Code reviews get longer and more mind-numbing, and people start to hate them.? Then, they start to?avoid them altogether, when possible.? The group’s collective dissatisfaction eventually leads to an overhaul of the process.

And the code review template sits there on SharePoint, untouched, like a digital fossil.

(more…)

Menu