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:

     $"{42}"

And the resulting integer is turned into a string:

     "42"

So we end up with this:

     DeserializeObject<int>("42");

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!