Quick Tips for Better C# Security

February 20, 2018Justin BoyerArticles, CodeIt.Right, JustinBoyer4

Application security is a hot topic. No one wants to write code that leads to the next data breach or major headline. C# security is on the minds of many .NET developers.

Secure coding involves detailed knowledge of a programming language and framework. There could be dozens of rules articulated here with detailed code examples showing right versus wrong coding practices. However, that might lead to quite a bit of dry reading and low retention. Instead, I’ll take a different angle. I’ll describe three principles that lead to strong, secure coding practices. Learn these principles well, and you’ll be able to secure any application you build.

(more…)

Can We Retire the Design Document, Already?

February 13, 2018Erik DietrichArticles, Documentation, ErikDietrichNo 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…)

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, GhostDocNo 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, CodeQuality12

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?

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, TechnicalDebt3

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