Thursday, August 31, 2017

Understanding the Microsoft Samples for .NET Core 2.0

So I finally took the leap into .NET Core with the release of .NET Core 2.0. I've shied away from Core because both the environment and the tools have been in flux. I tend to concentrate on things that are a bit more established so that I can get stuff done rather than try to figure out what's broken.

Note: .NET Core 2.0 Articles are collected here: Getting Started with .NET Core 2.0.

From the resources on the announcement article (Announcing .NET Core 2.0), I got environments successfully set up in Windows 10 with Visual Studio 2017 (15.3), Windows 10 with Visual Studio Code, and Mac macOS (10.12.6) with Visual Studio Code.

Where I ran into a bit of frustration was with the macOS sample (Getting started with .NET Core on macOS -- the same code is also used in the Visual Studio 2017 sample). I understand that the goal of this particular tutorial is to show how to create a library, consume a library, set up a unit test, and use a NuGet package, but there are a few things that I thought needed some explanation. (And a few things I'd like your opinion on.)
"Getting Started" tutorials need to be designed for developers who are really "getting started", not developers who "already know most of the things about the environment but need to learn this one new thing".
Note: I've copied this sample to my own GitHub repository since the Microsoft sample will (hopefully) change: GitHub - jeremybytes/microsoft-core20-samples.

I won't go into the details of configuring the environment and using Visual Studio Code. Those instructions are okay. But the code made me "huh?" quite a bit.

The Library
After creating a solution, the first step is to create a library project. Here's the code for that library file (also here: Thing.cs):

I'm generally okay with trivial examples: FizzBuzz or Fibonacci work for me. But this method really bothers be for a few reasons. The primary reason is that it's not immediately obvious why it's doing what it's doing.

So what is it doing? It is adding two numbers (two integers in, one integer out). But it's doing it in a bit of a strange way. Let's break it down by looking at some of the parts.

First, the string interpolation:

     $"{left + right}"

Let's say that we use the values 19 and 23 for "left" and "right", respectively:

     $"{19 + 23}"

Then the calculation is performed:


And the resulting integer is turned into a string:


So we end up with this:


And "deserializing" the string takes the string "42" and turns it back into the integer 42.

Ugh. Again, I understand that a big point (actually, the entire point) of this class is to show how to import a NuGet package (Newtonsoft.Json) and use that, but my big concern is that someone who is new to this (and maybe hasn't worked with JSON deserialization) will just be completely lost.

Another thing I would like to change with this class is the naming. "Thing" is a horrible class name. It's right up there with "Foo" and "Bar" in my world, and I've written many times about how much I hate those in samples.

And "Get" is completely the wrong name for the method. It really should be "Add". That change alone would make this class much more understandable.

The Console Application
There is another section where I was a bit put off by the sample code, and that is in the console application that consumes this library (code here: Program.cs):

The thing that bothers me here is that it looks like someone is playing code golf. I've written about this before in relation to reflection code: I Can Write That Method with 1 Line of Code.

This would be pretty difficult to debug into. If we set a breakpoint on the "WriteLine" and then choose "Step Into" where do we end up? That's not immediately obvious, particularly to someone who is new to the environment. For tutorial purposes, I'd probably break this up into 3 lines:

     var thing = new Thing();
     int result = thing.Get(19, 23);
     WriteLine($"The answer is {result}");

The Target Audience
Having this example in the Visual Studio 2017 tutorial doesn't bother me too much. That's because if someone has Visual Studio installed, they're probably already a .NET programmer who understands C#.

But if someone is using Visual Studio Code on macOS, I wouldn't make that same assumption. In fact, I'd make the opposite assumption: that this person is probably not familiar with C#. Anything that makes the code harder to understand (such as naming and too much work in interpolated strings) gets in the way of understanding how the environment works.

Quite honestly, if the macOS sample was my first look at Visual Studio Code with C#, I'd probably go back to my regular programming environment (whatever that is). The "Getting Started" tutorials need to be designed for developers who are really "getting started", not developers who "already know most of the things about the environment but need to learn this one new thing".

Wrap Up
I'll be working with .NET Core a bit more now that it's hit a fairly stable point. I'm still working through some of oddities of the environment. Once I get a better handle on what's going on, I'll put out some of my own samples for getting started.

Until then, feel free to let me know your opinions in the comments. Am I way off base on this? Or am I headed in the right direction?

This is part of the exploration process. I'm looking for the "I wish someone had shown me how to do it 'this way'". When I find it, I'll be sure to share it.

Happy Coding!

Monday, August 28, 2017

Jeremy on Cross Cutting Concerns

While I was at Detroit.Code(), I had the chance to sit down with Matthew Groves (@mgroves & website) and talk a bit about unit testing. You can hear the conversation on Matthew's Cross Cutting Concerns podcast.

Cross Cutting Concerns:
Jeremy Clark Convincing Your Boss on Unit Testing

We recorded this right after I did my talk "Unit Testing Makes Me Faster: Convincing Your Boss, Your Co-Workers, and Yourself". It's a great talk that I love to do, but I wish that I didn't need to convince people that unit testing is a good idea.

The problem is that many developers have had bad experiences with ineffective and/or useless tests. If you don't get the benefit, then it really is a waste of time. But when we take a closer look at what constitutes good tests, we find that they can make us more effective, efficient, and even faster.

Be sure to check out my upcoming events where you can see this talk in person. The next time will be a Visual Studio Live Chicago in mid-September. Feel free to contact me if you'd like me to come out to your company, developer event, or conference and help your group see the advantages of testing.

And if you'd like a deeper dive, I offer a full-day workshop to get developers started with good unit testing practices.

Happy Coding!

Saturday, August 12, 2017

Taking the Risk

Okay, so I did it. On Tuesday, I married my best friend, Kelly.

This is the high risk decision that I first mentioned back in November and again in January. It was a really huge step for both of us. I can't think of anyone else I'd rather share my journey with (obviously). We've been friends since college -- which was *many* years ago -- and we make awesome partners.

Gettin' Hitched
We went to the courthouse, and most of our immediate family shared the ceremony with us.

I leave it up to you to try to figure out which family members go with each of us.

This is why I moved to Washington back in June, which was a huge step in itself: I'd lived in the same apartment for 15 years and the same city for over 20. We're a bit in the wilderness (it's 30 miles to the nearest traffic signal), so that has been a transition for me. But it's really beautiful out here. I'm totally okay with trading 7-Eleven for wild blackberries.

I've taken lots of pictures since I've arrived: Living in Skagit County. (And a few when I visited in February: 1250 Miles, 2 Cats, and a Banjo.)

So, how do I know that Kelly is the right partner for me? Well, first of all, she made this chart for "Sharing Household Chores":

Next, when I saw these salt and pepper shakers at Target, she said that we had to buy them:

I don't think we need any more proof than that. (Although we do have some other things in common, too.)

Blended Family
Kelly and I have already seen some of the joys of our blended family: she had 2 dogs and I had 2 cats. Now together we have 2 dogs and 2 cats. The 6 of us are learning to get along together (sort of).

Toby & Amanda

Lulu & Mae

Lu & Toby trying to reach an agreement
Driving Home
The drive home from the courthouse was a bit tense. Each of us knew that we made the right decision, but the gravity of such a big step weighed us down a bit.

Fortunately, on the road home, we ran across a perfect example of "not my job". It was a bit unbelievable, so we had to turn around on the highway to get a picture:

The laughter was exactly what we needed.

To those of you who have been wishing me the best on my decision, Thank You.

Now the real adventure begins...

Tuesday, August 1, 2017

Jeremy on Technology and Friends

While I was in Detroit, I sat down with David Giard (@DavidGiard) for his Technology and Friends show. He gave me the chance to talk about my t-shirt and how I became a Social Developer.

Episode 490: Jeremy on Social Developers

If you'd like your own copy of the shirt, you can pick it up at the xkcd store: Just Shy.

Happy Coding!