Time Wasters for Programmers and How to Avoid Them

February 6, 2018Justin BoyerArticles, JustinBoyer1

Time is one resource we can’t replenish, and time wasters sap that precious resource. For programmers, using your time wisely can be the difference between really impressing your clients or employer and being the expendable one when things get tough.

Saving time is not always about good practices. It’s also about avoiding things that waste your time without you even noticing. Let’s take a look at some time wasters and how programmers can avoid them.

(more…)

GhostDoc v2018 Beta 3 is available

January 30, 2018Serge BaranovskyBeta, Documentation, GhostDoc, NewsNo Comments

(Mar 9, 2018) Update: new build v2018.0.18070 has been posted to address the VS2017 v15.6 compatibility issue.

Changes in the Beta 3, build v2018.0.18030 –

New feature – Document Project – now can generate XML Comment templates for a whole project
Added support for the <inheritdoc> tag – for type members only in the XML Comments as well as the generated help documentation. This allows using the tag instead of copying the documentation from base members and synchronizing the changes.
Visual Editor improvements
- New commands – Add Table, Remove Table
- New commands – Add Note, Remove Note
- Now the tags not recognized by the Visual Editor are added back to the XML Comment when saving the edits
- Now render the Code Contract section preview
- A number of improvements that impact proper XML comment generation
Added /cleanup switch for the command line tool – when used will delete all files and folders in the output directory before creating help documentation.
Support for Code Contracts when generating help documentation
Added Options -> General -> ‘Keep solution properties file in the .vs folder’ allowing to hide the solution properties file (<solution path>.GhostDoc.xml) in the solution’s .vs folder
The Cleanup checkbox in the Build Help Documentation dialog has been changed to a button. Now the folder must be cleaned up manually – this is to prevent accidental file loss when the output folder picked at an incorrect location.
Default toolbar icon is now Build Help Documentation where previously was Comment Preview

For the complete list of changes, see What’s New in GhostDoc v2018 Beta

For information on the original Beta release, please see the Visual Editing for XML Comments post.

Download GhostDoc Pro Beta

Version note

We changed the way we do the versioning for our products to keep it straightforward and simple. The new upcoming major GhostDoc version is to be v2018.x instead of the v6 we initially announced. Going forward we will name the major versions by the year of the release.

Feedback

We appreciate your feedback on the new features; please email us at support@submain.com or post in the GhostDoc Beta Forum.

CodeIt.Right Rules Explained 13 includes

CodeIt.Right Rules Explained, Part 13

January 30, 2018Erik DietrichArticles, CodeIt.Right, CodeQuality, ErikDietrich, Rules, RulesExplained1

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 DietrichArticles, CodeQuality, CodeReviews, ErikDietrich2

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

Coding Best Practices When You’re Short On Time

January 16, 2018Carlos SchultsArticles, CarlosSchults, CodeQualityNo 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

January 9, 2018Carlos SchultsArticles, CarlosSchults, CodeIt.Right, CodeQuality8

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.

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?

January 3, 2018Carlos SchultsArticles, CarlosSchults, CodeIt.Right, CodeQuality, CodeReviews3

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

Pair Programming > Code Review

— Rafael Ponte (@rponte) November 19, 2017

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

December 19, 2017Peter MorlionArticles, CodeQuality, GhostDoc, PeterMorlion, TechnicalDebtNo 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…)

Released: CodeIt.Right v3.2

December 13, 2017Serge BaranovskyCodeIt.Right, News, Releases, UpdatesNo Comments

A new CodeIt.Right update is available now – version v3.2 – includes VS2017 performance improvements, minor enhancements, and bug fixes:

Resolved: Improved performance loading solutions in VS2017 by moving it to an async thread
Resolved: Code quality hints now showing up correctly in VS2010-2015 Editor
Resolved: DoNotCatchSpecifiedExceptionTypes rule in VB now works correctly when the Catch clause has a When section
Resolved: Exception when “Analyze checked out files” is ON and a source file renamed or removed from disk
Resolved: AsyncMethodShouldHaveAwaitStatement rule no longer shows a violation when the await statement is on right side of assignment
Resolved: Now don’t run new version check when in Debug mode
Added: Support for StyleCop VSIX v5.0

For the complete and detailed list of the v3.2 changes see What’s New in CodeIt.Right v3.0

How do I try it?

Download the v3.0 at http://submain.com/download/codeit.right/

Feedback is what keeps us going!

Let us know what you think of the new version here – http://submain.com/support/feedback/

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 BeleyArticles, General, RickBeley, TeamStandard26

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