blogging jekyll comments suggest edit

The older I get, the less I want to worry about hosting my own website. Perhaps this is the real reason for the rise of cloud hosting. All of us old fogeys became too lazy to manage our own infrastructure.

For example, a while back my blog went down and as I frantically tried to fix it, I received this helpful piece of advice from Zach Holman.

@haacked the ops team gets paged when http://zachholman.com is down. You still have a lot to learn, buddy.

Indeed. Always be learning.

What Zach refers to is the fact that his blog is hosted as a GitHub Pages repository. So when his blog goes down (ostensibly because GitHub Pages is down), the amazing superheroes of the GitHub operations team jumps into action to save the day. These folks are amazing. Why not benefit from their expertise?

So I did.

One of the beautiful things about GitHub Pages is that it supports Jekyll, a simple blog aware static site generator.

If you can see this blog post, then the transition of my blog over to Jekyll is complete and (mostly) successful. The GitHub repository for this blog is located at https://github.com/haacked/haacked.com. Let me know if you find any issues. Or better yet, click that edit button and send me a pull request!

Screen grab from the 1931 movie Dr. Jekyll and Mr. Hide public domain

There are two main approaches you can take with Jekyll. In one approach, you can use something like Octopress to generate your site locally and then deploy the locally generated output to a gh-pages branch. Octopress has a nice set of themes (my new design is based off of the Greyshade theme) and plugins you can take advantage of with this approach. The downside of that approach is you can’t publish a blog post solely through GitHub.com the website.

Another approach is to use raw Jekyll with GitHub pages and let GitHub Pages generate your site when your content changes. The downside of this approach is that for security reasons, you have a very limited set of Jekyll plugins at your disposal. Even so, there’s quite a lot you can do. My blog is using this approach.

This allows me to create and edit blog posts directly from the web interface. For example, every blog post has an “edit” link. If you click on that, it’ll fork my blog and take you to an edit page for that blog post. So if you’re a kind soul, you could fix a typo and send me a pull request and I can update my blog simply by clicking the Merge button.

Local Jekyll

Even with this latter approach, I found it useful to have Jekyll running locally on my Windows machine in order to test things out. I just followed the helpful instructions on this GitHub Help page. If you are on Windows, you will inevitably run into some weird UTF Encoding issue. The solution is fortunately very easy.

Migrating from Subtext

Previously, I hosted my blog using Subtext, a database driven ASP.NET application. In migrating to Jekyll, I decided to go all out and convert all of my existing blog posts into Markdown. I wrote a hackish ugly console application, Subtext Jekyll Exporter, to grab all the blog post records from my existing blog database.

The app then shells out to Pandoc to convert the HTML for each post into Markdown. This isn’t super fast, but it’s a one time only operation.

If you have a blog stored in a database, you can probably modify the Subtext Jekyll Exporter to create the markdown post files for your Jekyll blog. I apologize for the ugliness of the code, but I have no plans to maintain it as it’s done its job for me.

The Future of Subtext

It’s with heavy heart that I admit publicly what everyone has known for a while. Subtext is done. None of the main contributors, myself included, have made a commit in a long while.

I don’t say dead because the source code is available on GitHub under a permissive open source license. So anyone can take the code and continue to work on it if necessary. But the truth is, there are much better blog engines out there.

I started Subtext with high hopes eight years ago. Despite a valiant effort to tame the code, what I learned in that time was that I should have started from scratch.

I was heavily influenced by this blog post from Joel Spolksy, Things You Should Never Do.

Well, yes. They did. They did it by making the single worst strategic mistake that any software company can make:

They decided to rewrite the code from scratch.

Perhaps it is a strategic mistake for a software company, but I’m not so sure the same rules apply to an open source project done in your spare time.

So much time and effort was sacrificed at the altar of backwards compatibility as we moved mountains to make the migration from previous versions to next continue to work while trying to refactor as much as possible. All that time dealing with the past was time not spent on innovative new features. I was proud of the engineering we did to make migrations work as well as they did, but I’m sad I never got to implement some of the big ideas I had.

Despite the crap ton of hours I put into it, so much so that it strained my relationship at times, I don’t regret the experience at all. Working on Subtext opened so many doors for me and sparked many lifelong friendships.

So long Subtext. I’ll miss that little submarine.

code, rx comments suggest edit

Judging by the reaction to my Death to the If statement where I talked about the benefits of declarative code and reducing control statements, not everyone is on board with this concept. That’s fine, I don’t lose sleep over people being wrong.

Photo by Grégoire Lannoy CC BY 2.0

My suspicion is that the reason people don’t have the “aha! moment” is because examples of “declarative” code are too simple. This is understandable because we’re trying to get a concept across, not write the War and Peace of code. A large example becomes unwieldy to describe.

A while back, I tried to tackle this with an example using Reactive Extensions. Imagine the code you would write to handle both the resize and relocation of a window, where you want to save the position to disk, but only after a certain interval has passed since the last of either event.

So you resize the window, then before the interval has passed you move the window. And only have you stop moving it and resizing it for this interval, does it save to disk.

Set aside your typical developer bravado and think about what that code looks like in a procedural or object oriented language. You functional reactive programmers can continue to smirk smugly.

The code is going to be a bit gnarly. You will have to write bookkeeping code such as saving the time of the last event so you can check that the duration has passed. This is because you’re telling the computer how to throttle.

With declarative code, you more or less declare what you want. “Hey! Give me a throttle please!” (Just because you are declaring, it doesn’t mean you can’t be polite. I like to add a Please suffix to all my methods). And declarations are much easier to compose together.

This example is one I wrote about in my post Make Async Your Buddy with Reactive Extensions. But I made a mistake in the post. Here’s the code I showed as the end result:

Observable.Merge(
    Observable.FromEventPattern
      <SizeChangedEventHandler, SizeChangedEventArgs>
        (h => SizeChanged += h, h => SizeChanged -= h)
        .Select(e => Unit.Default),
    Observable.FromEventPattern<EventHandler, EventArgs>
        (h => LocationChanged += h, h => LocationChanged -= h)
        .Select(e => Unit.Default)
).Throttle(TimeSpan.FromSeconds(5), RxApp.DeferredScheduler)
.Subscribe(_ => this.SavePlacement());

I’ll give you a second to recover from USBS (Ugly Syntax Blindness Syndrome).

The code isn’t incorrect, but there’s a lot of noise in here due to the boilerplate expressions used to convert an event into an observable sequence of events. I think this detracted from my point.

So today, I realized I should add a couple of really simple extension methods that describe what’s going on and hides the boilerplate.

// Returns an observable sequence of a framework element's
// SizeChanged events.
public static IObservable<EventPattern<SizeChangedEventArgs>> 
    ObserveResize(this FrameworkElement frameworkElement)
{
  return Observable.FromEventPattern
    <SizeChangedEventHandler, SizeChangedEventArgs>(
        h => frameworkElement.SizeChanged += h,
        h => frameworkElement.SizeChanged -= h)
      .Select(ep => ep.EventArgs);
}

// Returns an observable sequence of a window's 
// LocationChanged events.
public static IObservable<EventPattern<EventArgs>> 
    ObserveLocationChanged(this Window window)
{
  return Observable.FromEventPattern<EventHandler, EventArgs>(
      h => window.LocationChanged += h,
      h => window.LocationChanged -= h)
    .Select(ep => ep.EventArgs);
}

This then allows me to rewrite the original code like so:

this.ObserveResize()
  .Merge(this.ObserveLocationChanged())
  .Throttle(TimeSpan.FromSeconds(5), RxApp.MainThreadScheduler)
  .Subscribe(_ => SavePlacement());

That code is much easier to read and understand what’s going on and avoids the plague of USBS (unless you’re a Ruby developer in which case you have a high sensitivity to USBS).

The important part is we don’t have to maintain tricky bookkeeping code. There’s no code here that keeps track of the last time we saw one or the other event. Here, we just declare what we want and Reactive Extensions handles the rest.

This is what I mean by declare, don’t tell. We don’t tell the code how to do its job. We just declare what we need done.

UPDATE: ReactiveUI (RxUI) 5.0 has an assembly Reactive.Events that maps every event to an observable for you! For example:

control.Events()
  .Clicked
  .Subscribe(_ => Console.WriteLine("foo"));

That makes things much easier!

code comments suggest edit

Not long ago I wrote a blog post about how platform restrictions harm .NET. This led to a lot of discussion online and on Twitter. At some point David Kean suggested a more productive approach would be to create a UserVoice issue. So I did and it quickly gathered a lot of votes.

I’m visiting Toronto right now so I’ve been off of the Internet all day and missed all the hubbub when it happened. I found out about it when I logged into Gmail and I saw I had an email that the user voice issue I created was closed. My initial angry knee-jerk reaction was “What?! How could they close this without addressing it?!” as I furiously clicked on the subject to read the email and follow the link to this post.

Bravo!

Serious Kudos to the .NET team for this. It looks like most of the interesting PCL packages are now licensed without platform restrictions. As an example of how this small change sends out ripples of goodness, we can now make Octokit.net depend on portable HttpClient and make Octokit.net itself more cross platform and portable without a huge amount of work.

I’m also excited about the partnership between Microsoft and Xamarin this represents. I do believe C# is a great language for cross-platform development and it’s good to see Microsoft jumping back on board with this. This is a marked change from the situation I wrote about in 2012.

code comments suggest edit

Over the past few years I’ve become more and more interested in functional programming concepts and the power, expressiveness, and elegance they hold.

But you don’t have to abandon your language of choice and wander the desert eating moths and preaching the gospel of F#,  Haskell, or Clojure to enjoy these benefits today!

In his blog post, Unconditional Programming, Michael Feathers ponders how less control structures lead to better code,

Control structures have been around nearly as long as programming but it’s hard for me to see them as more than an annoyance.  Over and over again, I find that better code has fewer if-statements, fewer switches, and fewer loops.  Often this happens because developers are using languages with better abstractions.  They aren’t consciously trying to avoid control structures but they do.

We don’t need to try and kill every if statement, but perhaps the more we do, the better our code becomes.

Msi_if_coverPhoto from wikimedia: Cover of If by the artist Mindless Self Indulgence

He then provides an example in Ruby of a padded “take” method.

…I needed to write a ‘take’ function to take elements from the beginning of an array.  Ruby already has a take function on Enumerable, but I needed to special behavior.  If the number of elements I needed was larger than the number of elements in the array, I needed to pad the remaining space in the resulting array with zeros.

I recommend reading his post. It’s quite interesting. At the risk of spoiling the punch line, here’s the before code which makes use of a conditional…

  def padded_take ary, n
    if n <= ary.length
      ary.take(n)
    else
      ary + [0] * (n - ary.length)
  end
  end

… and here is the after code without the conditional. In this case, he pads the source array with just enough elements as needed and then does the take.

  def pad ary, n
    pad_length = [0, n - ary.length].max
    ary + [0] * pad_length
  end

  def padded_take ary, n
    pad(ary, n).take(n)
  end

I thought it would be interesting to translate the after code to C#. One thing to note about the Ruby code is that it always allocates a new array whether it’s needed or not.

Now, I haven’t done any benchmarks on it so I have no idea if that’s bad or not compared to how often the code is called etc. But it occurred to me that we could use lazy evaluation in C# and completely circumvent the need to allocate a new array while still being expressive and elegant.

I decided to write it as an extension method (I guess that’s similar to a Mixin for you Ruby folks?).

public static IEnumerable<T> PaddedTake<T>(
  this IEnumerable<T> source, int count)
{
  return source
    .Concat(Enumerable.Repeat(default(T), count))
    .Take(count);
}

This code takes advantage of some Linq methods. The important thing to note is that Concat and Repeat are lazily evaluated. That’s why I didn’t need to do any math to figure out the difference in length between the source array and the the take count.

I just passed the total count we want to take to Repeat. Since Repeat is lazy, we could pass in int.MaxValue if we wanted to get all crazy up in here. I just passed in count as it will always be enough and I like to play it safe.

Now my Ruby friends at work might scoff at all those angle brackets and parentheses in the code, but you have to admit that it’s an elegant solution to the original problem.

Here is a test to demonstrate usage and show it works.

var items = new[] {1, 2, 3};

var result = items.PaddedTake(5).ToArray();

Assert.Equal(5, result.Length);
Assert.Equal(1, result[0]);
Assert.Equal(2, result[1]);
Assert.Equal(3, result[2]);
Assert.Equal(0, result[3]);
Assert.Equal(0, result[4]);

I also ran some quick perf tests on it comparing PaddedTake to the built in Take . PaddedTake is a tiny bit slower, but the amount is like the extra light cast by a firefly at noon of a sunny day. The performance of this method is way more affected by the number of elements in the array and the number of elements you are taking. But in my tests, the performance of PaddedTake stays pretty close to Take as we grow the array and the take.

I think it’d be interesting to have a build task that reported back the number of `if` statements and other control structures per line of code and see if you can bring that down over time. In any case, I hope this helps you improve your own code!

open source, code comments suggest edit

Octokit.net targets multiple platforms. This involves a large risk to my sanity. You can see the general approach here in the Octokit directory of our project:

 octokit-projects

Mono gets a project! MonoAndroid gets a project file! Monotuch gets a project file! Everybody gets a project file!

Each of these projects references the same set of .cs files. When I add a file to Octokit.csproj, I have to remember to add that file to the other four project files. As you can imagine, this is easy to forget.

It’s a real pain. So I opened up a feature request on FAKE, the tool we use for our build (more on that later) and asked them for a task that would fail the build if another project file in the same directory was missing a file from the “source” project file. I figured this would be something easy for F# to handle.

The initial response from the maintainer of FAKE, Steffen Forkman, was this:

What you need is a better project system ;-)

Touché!

This problem (along with so many project file merge conflicts) would almost completely go away with file patterns in project files. I’ve been asking for this for a long time (I asked the Visual Studio team for this the day I joined Microsoft, or maybe it was the first month, I don’t recall). There’s a User Voice item requesting this,go vote it up! (Also, go vote up thisplatform restriction issuethat’s affecting Octokit.net as well)

In any case, sorry to say unlimited chocolate fountains don’t exist and I don’t have the project system I want. So let’s deal with it.

A few days later, I get this PR to octokit.net. When I ran the build, I see the following snippet in the build output.

Running build failed.
Error:
System.Exception: Missing files in  D:\Octokit\Octokit-MonoAndroid.csproj:
Clients\OrganizationMembersClient.cs

That’s telling me that somebody forgot to add the class OrganizationMembersClient.cs to the Octokit-MonoAndroid.csproj. Wow! Isn’t open source grand?

A big thanks to Steffen and other members of the FAKE community who pitched in to build a small but very useful feature. In a follow-up post, I’ll write a little bit about why we moved to using FAKE to build Octokit.net.

Update

I opened an issue to take this to the next step. Rather than just verify the project files, I want some way to automatically modify or generate them.

Update 2

FAKE just got even better with the new FixProjects task! For now, we’ve added this as an explicit command.

.\build FixProjects

Over time, we may just integrate this into the Octokit.net build directly.

open source, code, github comments suggest edit

Most developers are aware of the potential pitfalls of premature optimization and premature generalization. At least I hope they are. But what about premature standardization, a close cousin to premature generalization?

It’s human nature. When patterns emerge, they tempt people to drop everything and put together a standard to codify the pattern. After all, everyone benefits from a standard, right? Isn’t it a great way to ensure interoperability?

Yes, standards can be helpful. But to shoehorn a pattern into a standard prematurely can stifle innovation. New advances are often evolutionary. Multiple ideas compete and the best ones (hopefully) gain acceptance over time while the other ideas die out from lack of interest.

Once standardization is in place, people spend so much energy on abiding by the standard rather than experiment with alternative ideas. Those who come up with alternative ideas become mocked for not following “the standard.” This is detrimental.

In his Rules of Standardization, Yaron Goland suggests that before we adopt a standard,

The technology must be very old and very well understood

He proposes twenty years as a good rule of thumb. He also suggests that,

Standardizing the technology must provide greater advantage to the software writing community then keeping the technology incompatible

This is a good rule of thumb to contemplate before one proposes a standard.

Social Standards

So far, I’ve focused on software interoperability standards. Software has a tendency to be a real stickler when it comes to data exchange. If even one bit is out of place, software loses its shit.

For example, if my code sends your code a date formatted as ISO 8601, but your code expects a date in Unix Time, stuffs gonna be broke™.

But social standards are different. By a “social standard” I mean a convention of behavior among people. And the thing about people is we’re pretty damn flexible, Hacker News crowd notwithstanding.

Rather than being enforced by software or specifications, social standards tend to be enforced through the use of encouragement, coercion, and shaming.

Good social standards are not declared so much as they emerge based on what people do already. If people converge on a standard, then it becomes the standard. And it’s only the standard so long as people adopt it.

This reminds me of a quote by W.L. Gore & Associates’ CEO, Terri Kelly on leadership at a non-hierarchical company,

If you call a meeting, and no one shows up, you’re probably not a leader, because no one is willing to follow you.

Standard GitHub issue labels?

I wrote a recent tweet to announce a label that the Octokit team uses to denote low hanging fruit for new contributors,

For those looking to get started with .NET OSS and http://Octokit.net, we tag low hanging fruit as “easy-fix”. https://github.com/octokit/octokit.net/issues?labels=easy-fix

It was not my intention to create a new social standard.

Someone questioned me why we didn’t use the “jump in” label proposed by Nik Molnar,

The idea for a standardized issue label for open source projects came from the two pieces of feedback I consistently hear from would-be contributors:

  1. “I’m not sure where to start with contributing to project X.”
  2. “I’ll try to pick off a bug on the backlog as soon as I’ve acquainted myself enough with the codebase to provide value.” “”

In the comments to that blog post, Glenn Block notes that the ScriptCS project is using the “YOU TAKE IT” label to accomplish the same thing.

About two and a half years earlier, I blogged about the “UpForGrabs” label the NuGet team was using for the same reason.

As you can see, multiple people over time have had the same idea. So the question was raised to me, would I agree that “standardizing” a label to invite contributors might be a good thing?

To rephrase one of Goland’s rule of standardization,

A social standard must provide greater advantage to the software community than just doing your own thing.

This is a prime example of a social standard and in this case, I don’t think it provides a greater advantage than each project doing it’s own thing. At least not yet. If one arises naturally because everyone thinks it’s a great idea, then I’m sold! But I don’t think this is something that can just be declared to be a standard. It requires more experimentation.

I think the real problem is that these labels are just not descriptive enough. One issue I have with Up For Grabs, You Take It,and Jump Inis they seem too focused on giving commands to the potential contributor, “HEY! YOU TAKE IT! WE DON’T WANT IT!”. They’re focused on the relationship of the core team to the issue. I think the labels should describe the issue and not how the core team wants new contributors to interact with the issue.

What makes an issue appeal to a new contributor is different from contributor to contributor. So rather than a generic “UpForGrabs” label, I think a set of labels that are descriptive of the issue make sense. People can then self-select the issues that appeal to them.

For many new contributors, an issue labeled as “easy-fix” is going to appeal to their need to dip their toe into OSS. For others, issues labeled as “docs-and-samples” will fit their abilities better.

So far, I’ve been delighted that several brand new OSS contributors sent us pull requests. It far surpassed my expectations. Of course, I don’t have a control Octokit.net project with the different labels, so I can’t rightly attribute it to the labels. Science doesn’t work that way. Even if we did, I doubt it’s the labels that made much of any difference here.

Again, this is not an attempt to propose a new standard. This is just an approach we’re experimenting with in Octokit.net. If you like this idea, please steal it. If you have a better idea, I’d love to hear it!

github comments suggest edit

Today on the GitHub blog, we announced the first release of Octokit.net.

Octokit is a family of client libraries for the GitHub API. Back in May, we released Octokit libraries for Ruby and Objective-C.

Today we’re releasing the third member of the Octokit family, Octokit.net, the GitHub API toolkit for .NET developers.

octokit-dotnet

GitHub provides a powerful set of tools for developers who build amazing software together. But these tools extend way beyond the website and Git clients.

The GitHub API provides a rich web based way to leverage GitHub.com within your own applications. The Octokit family of libraries makes it easy to call into the API. I can’t wait to see what you build with it.

The Project

Octokit.net is an open source project on GitHub so feel free to contribute with pull requests, issues, etc. You’ll notice that we call it a 0.1.0 release. As of today, it doesn’t implement every API endpoint that GitHub.com supports.

We wanted to make sure that it was in use by a real application so we focused on the endpoints that GitHub for Windows needs. If there’s an endpoint that is not implemented, please do log an issue. Or even better, send a pull request!

Our approach in implementing this library was to avoid being overly speculative. We tried to implement features as we needed them based on developing a real production application.

But now that it’s in the wild, we’re curious to see what other types of applications will need from the library.

Platform and Licensing Details

Octokit.net is licensed under the MIT license.

As of today, Octokit.net requires .NET 4.5. We also have a WinRT library for .NET 4.5 Core. This is because we build on top of HttpClient is not available in .NET 4.0.

There is a Portable HttpClient package that does work for .NET 4.0, but we won’t distribute it because it has platform limitations that are incompatible with our license.

I had hoped that its platform limitations would have been removed by now, but that sadly is not the case. If you’re wondering why that matters, read my post here.

However, if you check the repository out, you’ll notice that there’s a branch named haacked/portable-httpclient. If you only plan to deploy on Windows, you can build that branch yourself and make use of it.

Go Forth And Build!

I’ve had great fun working with my team at GitHub on Octokit.net the past few weeks. I hope you have fun building amazing software that extends GitHub in ways we never imagined. Enjoy!

open source, github, code, code review comments suggest edit

If I had to pick just one feature that embodies GitHub (besides emoji support of course , I’d easily choose the Pull Request (aka PR). According to GitHub’s help docs (emphasis mine),

Pull requests let you tell others about changes you’ve pushed to a GitHub repository. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.

Some folks are confused by the name “pull request.” Just think of it as a request for the maintainer of the project to “pull” your changes into their repository.

Here’s a screenshot of a pull request for GitHub for Windows where Paul Betts patiently explains why my code might result in the total economic collapse of the world economy.

sample code review

A co-worker code review is a good way to avoid the Danger Zone (slightly NSFW).

Code review is at the heart of the GitHub collaboration model. And for good reason! There’s a rich set of research about the efficacy of code reviews.

In one of my favorite software books, Facts and Fallacies of Software Engineering by Robert Glass, Fact 37 points out,

Rigorous inspections can remove up to 90 percent of errors from a software product before the first test case is run.

And the best part is, that reviews are cost effective!

Furthermore, the same studies show that the cost of inspections is less than the cost of the testing that would be necessary to find the same errors.

One of my other favorite software books, Code Complete by Steve McConnell, points out that,

the average defect detection rate is only 25 percent for unit testing, 35 percent for function testing, and 45 percent for integration testing. In contrast, the average effectiveness of design and code inspections are 55 and 60 percent.

Note that McConnell is referring to evidence for the average effectiveness while Glass refers to evidence for the peak effectiveness.

The best part though, is that Code Review isn’t just useful for finding defects. It’s a great way to spread information about coding standards and conventions to others as well as a great teaching tool. I learn a lot when my peers review my code and I use it as an opportunity to teach others who submit PRs to my projects.

Effective Code Review

You’ll notice that Glass and McConnell use the term “code inspection” and not review. A lot of time, when we think of code review, we think of simply looking the code up and down a bit, making a few terse comments about obvious glaring errors, and then calling it a day.

I know I’ve been guilty of this “drive-by” code review approach. It’s especially easy to do with pull requests.

But what these gentlemen refer to is a much more thorough and rigorous approach to reviewing code. I’ve found that when I do it well, a proper code review is just as intense and mentally taxing as writing code, if not more so. I usually like to take a nap afterwards.

Here are a few tips I’ve learned over the years for doing code reviews well.

Review a reasonable amount of code at a time

This is one of the hardest tips for me to follow. When I start a review of a pull request, I am so tempted to finish it in one sitting because I’m impatient and want to get back to my own work. Also, I know that others are waiting on the review and I don’t want to hold them up.

But I try and remind myself that code review is my work! Also, a poorly done review is not much better than no review at all. When you realize that code reviews are important, you understand that it’s worth the extra time to do it well.

So I usually stop when I reach that point of review exhaustion and catch myself skipping over code. I just take a break, move onto something else, and return to it later. What better time to catch up on Archer episodes?!

Focus on the code and not the author

This has more to do with the social aspect of code review than defect finding. I try to do my best to focus my comments on the code and not the ability or the mental state of the author. For example, instead of asking “What the hell were you thinking when you wrote this?!” I’ll say, “I’m unclear about what this section of code does. Would you explain it?”.

See? Instead of attacking the author, I’m focusing on the code and my understanding of it.

Of course, it’s possible to follow this advice and still be insulting, “This code makes me want to gouge my eyes out in between my fits of vomiting.” While this sentence focuses on the code and how it makes me feel, it’s still implicitly insulting to the author. Try to avoid that.

Keep a code review checklist

A code review checklist is a really great tool for conducting an effective code review. The checklist should be a gentle reminder of common issues in code you want to review. It shouldn’t represent the only things you review, but a minimal set. You should always be engaging your brain during a review looking for things that might not be on your checklist.

I’ll be honest, as I started writing this post, I only had a mental checklist I ran through. In an effort to avoid being a hypocrite and leveling up my code review, I created a checklist gist.

My checklist includes things like:

  1. Ensure there are unit tests and review those first looking for test gaps. Unit tests are a fantastic way to grasp how code is meant to be used by others and to learn what the expected behavior is.
  2. Review arguments to methods. Make sure arguments to methods make sense and are validated. Consider what happens with boundary conditions.
  3. Look for null reference exceptions. Null references are a bitch and it’s worth looking out for them specifically.
  4. Make sure naming, formatting, etc. follow our conventions and are consistent.I like a codebase that’s fairly consistent so you know what to expect.
  5. Disposable things are disposed. Look for usages of resources that should be disposed but are not.
  6. Security.There is a whole threat and mitigation review process that falls under this bucket. I won’t go into that in this post. But do ask yourself how the code can be exploited.

I also have separate checklists for different platform specific items. For example, if I’m reviewing a WPF application, I’m looking out for cases where we might update the UI on a non-UI thread. Things like that.

Step Through The Code

You’ll note that I don’t mention making sure the code compiles and that the tests pass. I already know this through the magic of the commit status API which is displayed on our pull requests.

-396

However, for more involved or more risky code changes, I do think it’s worthwhile to actually try the code and step through it in the debugger. Here, GitHub has your back with a relatively new feature that makes it easy to get the code for a specific pull request down to your machine.

If you have GitHub for Windows or GitHub for Mac installed and you scroll down to the bottom of any pull request, you’ll see a curious new button.

clone-pr-in-desktop

Click on that button and we’ll clone the pull request code to your local machine so you can quickly and easily try it out.

Note that in Git parlance, this is not the original pull request branch, but reference (usually named something like pr/42 where 42 is the pull request number) so you should treat it as a read-only branch. But you can always create a branch from that reference and push it to GitHub if you need to.

I often like to do this and run Resharper analysis on the code to highlight things like places where I might want to convert code to use a LINQ expression and things like that.

Sign Off On It

After a few rounds of review, when the code looks good, make sure you let the author know! Praise where praise is due is an important part of code reviews.

At GitHub, when a team is satisfied with a pull request, we tend to comment it and include the ship it squirrel emoji (:shipit:) . That indicates the review is complete, everything looks good, and you are free to ship the changes and merge it to master.

Every team is different, but on the GitHub for Windows team we tend to let the author merge the code into master after someone else signs off on the pull request.

This works well when dealing with pull requests from people who also have commit access. On my open source projects, I tend to post a thumbs up reaction gif to show my immense appreciation for their contribution. I then merge it for them.

Here’s one of my favorites for a very good contributions.

Bruce Lee gives a thumbs up

Be Good To Each Other

Many of my favorite discussions happen around code. There’s something about having working code to focus a discuss in a way that hypothetical discussions do not.

Of course, even this can break down on occasion. But for the most part, if you go into a code review with the idea of both being taught as well as teaching, good things result.

community, personal comments suggest edit

I love a good argument. No really! Even ones online.

The problem is, so few of them are any good. They tend to go nowhere and offer nothing of value. They just consist of one side attempting to browbeat the other into rhetorical submission.

What?! You are not persuaded by my unassailable argument? THEN LET ME MAKE THE SAME POINTWITH ALL CAPS!

ARE YOU NOT CONVINCED?!

red-cardYou want to argue? Argue with this card! Image: from wikipedia CC BY-SA 3.0.

So what makes an argument good? (besides when you agree with me which is always a good move)

A while back, I read an interesting article about Professor Daniel H. Cohen, a philosopher who specializes in argumentation theory, that tackles this question.

As an aside, I wonder how his kids feel arguing with someone who’s basically a professor of arguing? Must be hard winning that argument about extending that curfew.

The article starts off with a scenario that captures 99.9% of arguments (online or offline) well:

You are having a heated debate with friends about, say, equality of the sexes. You’ve taken a standpoint and you’re sticking with it. Before you know it, you’ve got so worked up that, regardless of whether you believe your argument is the most valid, you simply just want to win, employing tactics and subterfuge to seek victory.

I like to think of myself as a very logical reasonable person. But when I read this scenario, I realized how often I’ve fallen prey to that even in what should be dispassionate technical arguments!

I’m pretty sure I’m not the only one. I’m just willing to admit it.

Cohen points out that the “war metaphor” is at fault for this tendency. Often, it’s the so-called “losers” of an argument who really win:

He explains, “Suppose you and I have an argument. You believe a proposition, P, and I don’t. I’ve objected, I’ve questioned, I’ve raised all sorts of counter-considerations, and in every case you’ve responded to my satisfaction. At the end of the day, I say, ‘You know what? I guess you’re right.’ So I have a new belief. And it’s not just any belief, but it’s a well-articulated, examined and battle-tested belief. Cohen continues, “So who won that argument? Well, the war metaphor seems to force us into saying you won, even though I’m the only one who made any cognitive gain.

The point of a good argument isn’t for one person to simply win over the other. It’s ideally for both to come away with cognitive gains.

Even if the goal of an argument is to reach a decision, the goal isn’t to win, the goal is to define the parameters for a good decision and then make the best possible decision with that in mind.

I’ve come to believe that when two reasonably smart people disagree on a subject, at the core, it is often because one of the following:

  1. One or both of the participants is missing key information.
  2. One or both of the participants made a logic error that leads to a wrong conclusion.
  3. The participants agree on the facts, but have different values and priorities leading them to either disagree on what conclusion should come from the facts.

In my mind, a good debate tries to expose missing facts and illogical conclusions so that two in the debate can get to the real crux of the matter, how their biases, experiences, and values shape their beliefs.

I’m assuming here that both participants are invested in the debate. When one isn’t, it becomes overwhelmingly tempting to resort to any means necessary in order to wipe that smug smirk off your opponent’s face.

Troll_Face

Of course, both sides will believe they’re the one who is drawing conclusions from years of objective rational analysis, but they’re both wrong. In the end, we all succumb to various biases and our values. And a good debate can expose those and allow participants to discuss whether those are the right biases and values to have in the first place? That’s where an argument really gets somewhere.

Another philosopher, Daniel Dennett, lays out these rhetorical habits when critiquing or arguing in his book, Intuition Pumps And Other Tools for Thinking:

How to compose a successful critical commentary:

​1. Attempt to re-express your target’s position so clearly, vividly and fairly that your target says: “Thanks, I wish I’d thought of putting it that way.”

​2. List any points of agreement (especially if they are not matters of general or widespread agreement).

​3. Mention anything you have learned from your target.

​4. Only then are you permitted to say so much as a word of rebuttal or criticism.

These habits nicely complement the improved metaphor for arguing espoused by Cohen.

So the next time you get into an argument, think about your goals. Are you just trying to win or are you trying to reach mutual understanding? Then try to apply Dennett’s rhetorical habits as you argue. I’ll try to do the same so if we end up in an argument, there’s a better chance it’ll result in a good one.

This will serve you well not only in your work, but in your personal relationships as well.

code, open source comments suggest edit

Just shipped a new release of RestSharp to NuGet. For those who don’t know, RestSharp is a simple REST and HTTP API Client for .NET.

This release is primarily a bug fix release with a whole lotta bug fixes. It should be fully compatible with the previous version. If it’s not, I’m sorry.

Some highlights:

  • Added Task<T> Overloads for async requests
  • Serialization bug fixes
  • ClientCertificate bug fix for Mono
  • And many more bug fixes…

Full release notes are up on GitHub. If you’re interested in the nitty gritty, you can see every commit that made it into this release using the GitHub compare view.

I want to send a big thanks to everyone who contributed to this release. You should feel proud of your contribution!

Who are you and what did you do to Sheehan?!

Don’t worry! John Sheehan is safe and sound in an undisclosed location. Ha! I kid. I’m beating him senseless every day.

Seriously though, if you use RestSharp, you should buy John Sheehan a beer. Though get in line as Paul Betts owes him at least five beers.

-359John started RestSharp four years ago and has shepherded it well for a very long time. But a while back he decided to focus more on other technologies. Even so, he held on for a long time tending to his baby even amidst a lot of frustrations, until he finally stopped contributing and left it to the community to handle.

And the community did. Various other folks started taking stewardship of the project and it continued along. This is the beauty of open source.

We at GitHub use RestSharp for the GitHub for Windows application. A little while back, I noticed people stopped reviewing and accepting my pull requests. Turns out the project was temporarily abandoned. So Sheehan gave me commit access and I took the helm getting our bug fixes in as well as reviewing and accepting the many dormant pull requests. That’s why I’m here.

Why RestSharp when there’s HttpClient?

Very good question! System.Net.HttpClient is only available for .NET 4.5. There’s the Portable Class Library (PCL) version, but that is encumbered by silly platform restrictions. I’ve written before that this is harms .NET. I am hopeful they will eventually change it.

RestSharp is unencumbered by platform restrictions - another beautiful thing about open source.

So until Microsoft fixes the licensing on HttpClient, RestSharp is one of the only options for a portable, multi-platform, unencumbered, fully open source HTTP client you can use in all of your applications today. Want to build the next great iOS app using Xamarin tools? Feel free to use RestSharp. Find a bug in using it on Mono? Send a pull request.

The Future of RestSharp

I’m not going to lie. I’m just providing a temporary foster home for RestSharp. When the HttpClient licensing is fixed, I may switch to that and stop shepherding RestSharp. I fully expect others will come along and take it to the next level. Of course it really depends on the feature set it supplies and whether they open source it.

As they say, open source is about scratching an itch. Right now, I’m scratching the “we need fixes in RestSharp” itch. When I no longer have that itch, I’ll hand it off to the next person who has the itch.

But while I’m here, I’m going to fix things up and make them better.

code, open source, github comments suggest edit

The first GitHub Data Challenge launched in 2012 and asked the following compelling question: what would you do with all this data about our coding habits?

The GitHub public timeline is now easy to query and analyze. With hundreds of thousands of events in the timeline every day, there are countless stories to tell.

Excited to play around with all this data? We’d love to see what you come up with.

It was so successful, we did it again this past April. One of those projects really caught my eye, a site that analysise Popular Coding Conventions on GitHub. It ended up winning second place.

It analyzes GitHub and provides interesting graphs on which coding conventions are more popular among GitHub users based on analyzing the code. This lets you fight your ever present software religious wars with some data.

For example, here’s how the Tabs vs Spaces debate lands among Java developers on GitHub.

java-tabs-vs-spaces

With that, I’m sure nobody ever will argue tabs over spaces again right? RIGHT?!

What about C#?!

UPDATE: JeongHyoon Byun added C# support! Woohoo!

Sadly, there is no support for C# yet. I logged an issue in the repository about that a while back and was asked to provide examples of C# conventions.

I finally got around to it today. I simply converted the Java examples to C# and added one or two that I’ve debated with my co-workers.

However, to get this done faster, perhaps one of you would be willing to add a simple CSharp convention parser to this project. Here’s a list of the current parsers that can be used as the basis for a new one.

Please please please somebody step up and write that parser. That way I can show my co-worker Paul Betts the error of his naming ways.

humor, personal, company culture comments suggest edit

I avoid mailing lists the same way I avoid fun activities like meetings and pouring lemon juice into bloody scrapes. Even so, I still somehow end up subscribed to one or two. Even worse, once in a while, despite my better judgment, I send an email to such a list and am quickly punished for my transgression with an onslaught of out of office auto replies. You know the type:

Hey there friend! Thanks for your email! No seriously, I’m thanking you even though I haven’t read it. I’m sure it’s important because I’m important.

Unfortunately (for you), I’m off to some island paradise drinking one too many Mai Tais and probably making an ass of myself.

If you need to reach me, you can’t, LOL! You can contact this list of people you don’t know in my absence. Good luck with that!

punishment Wait till you see the punishment for sending an email during the holidays! Photo by: Tomas Alexsiejunas license: CC BY 2.0

If you have such a rule set up, let me humbly offer you a friendly constructive tip:

NOBODY FUCKING CARES!

The universe has gone on for around 14 billion years before you were born just fine. And chances are, it’ll continue to survive after your death for another 100 googol years until the entropy death of the last proton, or another universe inflates to take its place. Whichever comes first.

So in the grand scheme of things, nobody cares that you’re out of the office, on vacation, or worse, too busy to respond to email so you automatically send me one as if I have all the time in the world to deal with more email.

Ok, that might have come across as a eensy weensy bit ranty. I’ll try to tone it down and offer something more constructive. After all, I’ve probably been guilty of this in my past and I apologize and have paid my penance (see photo above).

Maybe there’s a tiny bit of a purpose

The first time I experienced widespread use of out-of-office replies is during my time at Microsoft. And to be fair, it does serve a small purpose. While 99.999999% of the world doesn’t care if you’re out of the office (that’s science folks), sometimes someone has a legitimate need to know who they should contact instead of you. For example, at Microsoft, I had an internal reply set up that directed emails to my manager. The lucky guy.

Fortunately for those using Outlook with Exchange, you can choose a different reply for internal emails than external emails. So definitely go and do that.

The two email rule of out-of-office replies

But what about the rest of us who really don’t care? I offer the following simple idea:

If you must have an out-of-office auto reply, create a rule to only send it when you receive two direct emails without a response. The idea here is that if I send you one email directly, I can probably wait for you to get back to respond. If I can’t, I’ll send you another “hey, bump!” email and then receive auto notice. After all, if I send you two emails, sending me one is fair game.

Also, make sure you never ever ever send an auto-reply when you are not in the TO list. That rule alone will cut out billions of email list out-of-office spam. Ideally, the auto-reply should only occur if you’re the only one in the TO list. Chances are someone else in the TO list will know you’re gone and can reply to the others if necessary. Again, the two email rule could come into play here.

In the meanwhile, I think I’m going to switch tactics. Spam me, I spam you. So I may respond to those auto-replies with something like:

Dear So-and-so,

Hey dude, thanks for letting me know that you’re not in your office. I bet you’re on a really important business trip and/or vacation! I bet you have such important things to do there!

Me? Not so much. I wish I was on an important business trip and/or vacation.

It turns out, I have nothing better to do than respond to your automatically generated email to me! Thank you so much for that. The fact that it had your name at the bottom of the email and my email address in the TO: list was a nice personal touch. It really felt like you took the time to lovingly craft that email just for me.

So I thought it would be rude not to respond in kind with a thoughtful response of my own.

Sincerely and without regret,

Phil

p.s. I left you a little surprise in your office, but since you’re not there, I hope it doesn’t die before you get back. If it smells bad when you get back, you’ll know.

Hopefully email clients take this up and just implement it automatically because I don’t expect people to take the time to do this right.

What do you think? Are auto-replies more important than I give credit or do we live in a world with a lot of narcissists who must be stopped? Tell me how I’m right or wrong in the comments. Thanks!

code, community comments suggest edit

There’s something about being outdoors in Alaska that inspires poetic thoughts. In my case it’s all bad poetry so I’ll spare you the nausea and just show a photo instead.

This was taken descending from Flattop, a strenuous but easy climb. At the top, we couldn’t see more than ten yards because of the clouds. But as we descended, they suddenly cleared giving us a sliver of a view of the ocean and coastline.

flattop-hike

My first experience of Alaska was when my family moved out here from the tropical island of Guam. Yeah, it was a bit of a change. I went to high school there and returned to Anchorage every Christmas and Summer break during college.

When I lived there, I was completely oblivious to the existence of a software community out here. But around four years ago, I brought my family out to visit my parents and on a whim gave a talk to the local .NET user group.

This has become kind of a thing for me to try and find a local user group to speak at when I go on vacation.

This summer, after subjecting my wife to back to back weeks of travel, I decided to give her a long overdue break from family duties and take my kids to Alaska. One benefit of working at a mostly distributed company is I can pretty much work from any location that has good internet.

My parents were game to watch and entertain the kids while I worked from their house. Since I was up there, I also got in touch with folks about giving another talk.

Unfortunately, the .NET user group had disbanded not long after I left. They assured me it wasn’t my fault. It turns out that it is very difficult to get good speakers up there.

This isn’t too surprising. Alaska is pretty out-of-the way for most people. At the same time, it’s an amazing place to visit during the months of June and July. The days are long and sunny. There’s all sorts of outdoor activities to partake in.

So if you’re a decent speaker passionate about technology and happen to find yourself up there for vacation or otherwise, let me know and I can put you in touch with some people who would love to have you give a talk. You can probably even write-off a portion of your vacation if the talk is related to your work (though you should talk to your tax person about that and don’t listen to me).

alaska-github-talk

They put together an ad-hoc event while I was there and we had around twenty-five or so people show up. It doesn’t sound like a lot, but it’s a pretty good number for Anchorage and they really appreciate it. Afterwards, I recommend going out for some Alaskan Amber. It’s quite a good beer! And definitely hike Flattop.

open source comments suggest edit

A while back I wrote a riveting 3-part developer’s guide to copyright law and open source licensing for developers.

I’m pretty sure you read every word at the edge of your seat. Who doesn’t love reading about laws, licenses, and copyright!?

Seriously though, I hope some of you found it useful. In this post, I want to talk about some recent developments that should make it easier for developers to license their code.

Choosealicense.com

A couple days ago I published a blog post on the GitHub blog about an effort I’ve been involved with, http://choosealicense.com/. Per the about page:

GitHub wants to help developers choose a license for their source code.

If you already know what you’re doing and have a license you prefer to use, that’s great! We’re not here to change your mind. But if you are bewildered by the large number of OSS license choices, maybe we can help.

I’m interested in helping developers be explicit and clear about their intent for their code. Adding a LICENSE (or an UNLICENSE if that’s your thing) file to the root of your public repository is a good way to state your intent. We even include an option if you really do want to retain all rights to your code, you grinch (I kid! I do not judge.)

But before you can choose a license, you need to be informed about what the license entails. That’s what we hope the site helps with.

Combined with the site, GitHub now has a feature that lets you choose a license when creating a repository on GitHub.

AddALicense.com

That’s great! But what about all your existing projects? Well one of my co-workers, Garen Torikian, has you covered. He built http://addalicense.com/ as a little side project. Note that the project is full of disclaimers:

This site is **not owned by or affiliated with GitHub**. But I work there, and I’m using the API to add each new license file. You’ll be asked to authenticate this app for your public repositories on the next page.

Perhaps in the future, we may integrate this into http://choosealicense.com/.

But in the meanwhile check it out and get those projects licensed!

company culture comments suggest edit

A finely honed bullshit detector is a benefit to everyone. Let’s try a hypothetical conversation to test yours!

“Hey, we should release that under a more permissive license for XYZ reasons.”

“We’d like to, but the lawyers won’t let us.”

If it’s not malfunctioning, you should feel your bullshit detector tingling right now.

bull Yep, it’s a bull. Photo by Graeme Law CC BY 2.0

A lot of folks think that a lawyer’s job is to protect the business at all costs – that their job is to say “no!” Unfortunately, many places do structure it that way. After all, if a lawyer says “go ahead” and you get sued, the lawyer loses. But if the lawyer says “don’t”, there’s no immediate downside for the lawyer. Eventually the business may collapse from inaction, but there’s always teaching at law school as a backup. So why would the lawyer ever say “yes” in such a situation?

One of the best lessons I learned while at Microsoft was from Scott Guthrie when I expressed concern that the legal team wouldn’t let us break new ground with how we shipped open source.

He reminded me that the lawyers work for us. We do not work for the lawyers. If the lawyers had their way, we wouldn’t do anything because that’s the safest option.

You can see why so many people love the red polo.

Many decisions where legal gets involved are business decisions, not legal decisions. Unless the decision is downright illegal, the lawyer’s job is to help figure out how to do what’s best for the business. Along the way, they should make sure we’re aware of the risks, but also find ways to minimize the risks. At least that’s what a good lawyer does and I’ve been fortunate to work with some.

At the end of the day, even if the lawyer is uneasy about a course of action, they do not get to make the business decisions. That’s someone else’s job (unless you happen to work at a law firm I guess). Perhaps it’s your job.

So when someone tells you that “legal won’t let us do XYZ”, unless they follow that with “because it’s illegal and will land us all in jail and that’s no fun”, you should recognize it as a copout.

Sometimes what they mean is “I don’t really know what’s in the best interest of our business (or I’m too busy to care) so I’ll play it safe and blame the lawyers.”

What you hope they mean is “we won’t do this because it is not in the best interest of our business.” Now that is a fair answer. You may disagree, but it serves as a starting point for a more interesting conversation.

blogging, open source comments suggest edit

Google is shuttering Google Reader in a little over a day (on July 1st, 2013) as I write this. If you use Google Reader to read my blog, this means you might miss out on my posts and I KNOW YOU DON’T WANT THIS!

Then again, maybe this is finally your chance to make a break, get some fresh air, stop reading blogs and start creating! I won’t hold it against you.

But for the rest of you, it’s a good time to find a replacement. Or at the very least follow me on Twitter since I do tweet when I blog.

There’s a lot of Google Reader replacements out there, but only two that I like so far.

Feedly

feedly

Feedly is gorgeous. There are apps for many platforms, but the browser works pretty well. Also, you can use Google to log into it and import your Google Reader feeds. I hope Google allows exporting to Feedly and other aggregators after July 1st even as they close down the Google Reader site.

The problem I have with Feedly is that it doesn’t work like Google Reader. It wouldn’t be so bad if it had a better flow for reading items, but I find its interface to be quirky and in some cases, unintuitive. For example, it seems I have to mark items as read by clicking “mark above articles as read” rather than having it do it automatically like Reader does after you scroll past it.

This leads me to…

Go Read

go-read

Go Read is a late entry into the list, but there are three important things I really like about it:

  1. It is intended to be a clean and simple clone of Google Reader.
  2. It supports Google Reader’s keyboard shortcuts.
  3. It is open source and up on GitHub!

For some more details, check out the announcement blog post by the author, Matt Jibson, a developer at Stack Exchange:

I would like to announce the release of Go Read. It as a Google Reader clone, and designed to be close to its simplicity and cleanliness. I wanted to build something as close to Google Reader as made sense for one person to build in a few months.

It’s basically Google Reader, but without all the cruft and where you can send pull requests to improve things!

In fact, there’s already a few pull requests with some nice user interface polish that should hopefully make it into the site soon.

Despite some false starts, I have it up and running on my machine. I sent a few pull requests to update the README to help other clueless folks like me get it set up for hacking on.

So check it out, import your Google Reader feeds, and never miss out on another Haacked.com post EVER!

UPDATE: I forgot to mention what is perhaps the most important reason for me to prefer Go Read. I don’t want to end up in another Google Reader situation again and rely on an RSS Aggregator that isn’t a solid business and might not stick around. At least with an open source option, I have the code running on my own machine as a backup in a pinch.

code comments suggest edit

UPDATE: The .NET team removed the platform limitations.

Let me start by giving some kudos to the Microsoft BCL (Base Class Library) team. They’ve been doing a great job of shipping useful libraries lately. Here’s a small sampling on Nuget:

However, one trend I’ve noticed is that the released versions of most of these packages have a platform limitation in the EULA (the pre-release versions have an “eval-only” license which do not limit platform, but do limit deployment for production use). At this point I should remind everyone I’m not a lawyer and this is not legal advice blah blah blah.

Here’s an excerpt from section 2. c. in the released HttpClient license, emphasis mine:

a. Distribution Restrictions. You may not

  • alter any copyright, trademark or patent notice in the Distributable Code;
  • use Microsoft’s trademarks in your programs’ names or in a way that suggests your programs come from or are endorsed by Microsoft;
  • distribute Distributable Code to run on a platform other than the Windows platform;

I think this last bullet point is problematic and should be removed.

Why should they?

I recently wrote the following tweet in response to this trend:

Dear Microsoft BCL team. Please remove the platform limitation on your very cool libraries. Love, cross-platform .NET devs.

And a Richard Burte tweeted back:

And that pays the rent how exactly?

Great question!

There is this sentiment among many that the only reason to make .NET libraries cross platform or open source is just to appease us long haired open source hippies.

Well first, let me make it crystal clear that I plan to get a haircut very soon. Second, the focus of this particular discussion is the platform limitation on the compiled binaries. I’ll get to the extra hippie open source part later.

There are several reasons why removing the platform limitation benefits Microsoft and the .NET team.

It benefits Microsoft’s enterprise customers

Let’s start with Microsoft’s bread and butter, the enterprise. There’s a growing trend of enterprises that support employees who bring their own devices (BYOD) to work. As Wikipedia points out:

BYOD is making significant inroads in the business world, with about 75% of employees in high growth markets such as Brazil and Russia and 44% in developed markets already using their own technology at work.

Heck, at the time I was an employee, even Microsoft supported employees with iPhones connecting to Exchange to get email. I assume they still do, Ballmer pretending to break an iPhone notwithstanding.

Microsoft’s own software supports cross-platform usage. Keeping platform limitations on their .NET code hamstrings enterprise developers who want to either target the enterprise market or want to make internal tools for their companies that work on all devices.

It’s a long play benefit to Windows 8 Phone and Tablet

While developing Windows 8, Microsoft put a ton of energy and focus into a new HTML and JavaScript based development model for Windows 8 applications, at the cost of focus on .NET and C# in that time period.

The end result? From several sources I’ve heard that something like 85% of apps in the Windows app store are C# apps.

Now, I don’t think we’re going to see a bunch of iOS developers suddenly pick up C# in droves and start porting their apps to work on Windows. But there is the next generation to think of. If Windows 8 devices can get enough share to make it worthwhile, it may be easier to convince this next generation of developers to consider C# for their iOS development and port to Windows cheaply. Already, with Xamarin tools, using C# to target iOS is a worlds better environment than Objective-C. I believe iOS developers today tolerate Objective-C because it’s been so successful for them and it was the only game in town. As Xamarin tools get more notice, I don’t think the next generation will tolerate the clumsiness of the Objective-C tools.

There’s no good reason not to

Ok, this isn’t strictly speaking a benefit. But it speaks to a benefit.

The benefit here is that when Microsoft restricts developers without good reason, it makes them unhappy.

If you recall, Ballmer is the one who once went on stage to affirm Microsoft’s focus on developers! developers! developers! through interpretive dance.

ballmer-developers-dance

Unless there’s something I’m missing (and feel free to enlighten me!), there’s no good reason to keep the platform restriction on most of these libraries. In such cases, focus on the developers!

At a recent Outercurve conference, Scott Guthrie, a corporate VP at Microsoft in change of the Azure Development platform told the audience that his team’s rule of thumb with new frameworks is to default it to open source unless they have a good reason not to.

The Azure team recognizes that a strategy that requires total Windows hegemony will only lead to tears. Microsoft can succeed without having Windows on every machine. Hence Azure supports Linux, and PHP, and other non-Microsoft technologies.

I think the entire .NET team should look to what the Azure team is doing in deciding what their strategy regarding licensing should be moving forward. It makes more developers happy and costs very little to remove that one bullet point from the EULA. I know, I’ve been a part of a team that did it. We worked to destroy that bullet with fire (among others) in every ASP.NET MVC EULA.

Update: It looks like I may have overstated this. Licenses for products are based on templates. Typically a product team’s lawyer will grab a template and then modify it. So with ASP.NET MVC 1 and 2, we removed the platform restriction in the EULA. But it looks like the legal team switched to a different license template in ASP.NET MVC 3 and we forgot to remove the restriction. That was never the intention. Shame on past Phil. Present Phil is disappointed.

At least in this case, the actual source code is licensed under the Apache 2.0 license developers have the option to compile and redistribute, making this a big inconvenience but not a showstopper.

Next Steps

I recently commented on a BCL blog post suggesting that the team remove the platform limitation on a library. Immo Landwerth, a BCL Program Manager responded with a good clarifying question:

Thanks for sharing your concerns and the candid feedback. You post raised two very different items:

​(1) Windows only restriction on the license of the binaries

​(2) Open sourcing immutable collections

From what I read, it sounds you are more interested in (1), is this correct?

The post he refers to is actually one that Miguel de Icaza wrote when MEF came out with a license that had a platform restriction entitled Avoid the Managed Extensibility Framework. Fortunately, that was quickly corrected in that case.

But now we seem to be in a similar situation again.

Here was my response:

@Immo, well I’m interested in both. But I also understand how Microsoft works enough to know that (1) is much easier than (2). :P

So ultimately, I think both would be great, but for now, (1) is a good first step and a minimal requirement for us to use it in ReactiveUI etc.

So while I’d love to see these libraries be open source, I think a minimal next step would be to remove the platform limitation on the compiled library and all future libraries.

And not just to make us long haired (but soon to have a haircut) open source hippies happy, but to make us enterprise developers happy. To make us cross-platform mobile developers happy.

code comments suggest edit

One of the side projects I’ve been working on lately is helping to shepherd the Semantic Versioning specification (SemVer) along to its 2.0.0 release. I want to thank everyone who sent pull requests and engaged in thoughtful, critical, spirited feedback about the spec. Your involvement has made it better!

I also want to thank Tom for creating SemVer in the first place and trusting me to help move it along.

I’ve mentioned SemVer in the past as it relates to NuGet. The 2.0.0 release of SemVer addresses some of the issues I raised.

What’s Changed?

Not too much has changed. Most of the changes focus around clarifications.

Build metadata

Perhaps the biggest change is the addition of optional build metadata (what we used to call a build number). This simply allows you to add a bit of metadata to a version in a manner that’s compliant with SemVer.

The metadata does not affect version precedence. It’s analogous to a code comment.

It’s useful for internal package feeds and for being able to tie a specific version to some mechanism that generated it.

For existing package managers that choose to be SemVer 2.0 compliant, the logic change needed is minimal. Instead of reporting an error when encountering a version with build metadata, all they need to do is ignore or strip the build metadata. That’s pretty much it.

Some package managers may choose to do more with it (for internal feeds for example) but that’s up to them.

Pre-release identifiers

Pre-release labels have a little more structure to them now. For example, they can be separated into identifiers using the “.” delimiter and identifiers that only contain digits are compared numerically instead of lexically. That way, 1.0.0-rc.1 < 1.0.0-rc.11 as you might expect. See the specification for full details.

Clarifications

The rest of the changes to the specification are concerned with clarifications and resolving ambiguities. For example, we clarified that leading zeroes are not allowed in the Major, Minor, or Patch version nor in pre-release identifiers that only contain digits. This makes a canonical form for a version possible.

If you find an ambiguity, feel free to report it.

What’s Next?

As SemVer matures, we expect the specification to become a little more formal in nature as a means of removing ambiguities. One such effort underway is to include a BNF grammar for the structure of a version number in the spec. This should hopefully be part of SemVer 2.1.

code comments suggest edit

Code is unforgiving. As the reasonable human beings that we are, when we review code we both know what the author intends. But computers can’t wait to Well, Actually all over that code like a lonely Hacker News commenter:

Well Actually, Dave. I’m afraid I can’t do that.

Hal, paraphrased from 2001: A Space Odyssey

As an aside, imagine the post-mortem review of that code!

Code review is a tricky business. Code is full of hidden mines that lay dormant while you test just to explode in a debris of stack trace at the most inopportune time – when its in the hands of your users.

The many times I’ve run into such mines just reinforce how important it is to write code that is intention revealing and to make sure assumptions are documented via asserts.

Such devious code is often the most innocuous looking code. Let me give one example I ran into the other day. I was fortunate to defuse this mine while testing.

This example makes use of the Enumerable.ToDictionary method that turns a sequence into a dictionary. You supply an expression to produce a key for each element. In this example, loosely based on the actual code, I am using the CloneUrl property of Repository as the key of the dictionary.

IEnumerable<Repository> repositories = GetRepositories();
repositories.ToDictionary(r => r.CloneUrl);

It’s so easy to gloss over this line during a code review and not think twice about it. But you probably see where this is going.

While I was testing I was lucky to run into the following exception:

System.ArgumentException: 
An item with the same key has already been added.

Doh! There’s an implicit assumption in this code – that two repositories cannot have the same CloneUrl. In retrospect, it’s obvious that’s not the case.

Let’s simplify this example.

var items = new[]
{
    new {Id = 1}, 
    new {Id = 2}, 
    new {Id = 2}, 
    new {Id = 3}
};
items.ToDictionary(item => item.Id);

This example attempts to create a dictionary of anonymous types using the Id property as a key, but we have a duplicate, so we get an exception.

What are our options?

Well, it depends on what you need. Perhaps what you really want is a dictionary that where the value contains every item with the given key. The Enumerable.GroupBy method comes in handy here.

Perhaps you only care about the first value for a given key and want to ignore any others. The Enumerable.GroupBy method comes in handy in this case.

In the following example, we use this method to group the items by Id. This results in a sequence of IGrouping elements, one for each Id. We can then take advantage of a second parameter of ToDictionary and simply grab the first item in the group.

items.GroupBy(item => item.Id)
  .ToDictionary(group => group.Key, group => group.First());

This feels sloppy to me. There is too much potential for this to cover up a latent bug. Why should the other items be ignored? Perhaps, as in my original example, it’s fully normal to have more than one element for the key and you should handle that properly. Instead of grabbing the first item from the group, we retrieve an array.

items.GroupBy(item => item.Id)
  .ToDictionary(group => group.Key, group => group.ToArray());

In this case, we end up with a dictionary of arrays.

UPDATE: Or, as Matt Ellis points out in the comments, you could use theEnumerable.ToLookupmethod. I should have known such a thing would exist. It’s exactly what I need for my particular situation here.

What if having more than one element with the same key is not expected and should throw an exception. Well you could just use the normal ToDictionary method since it will throw an exception. But that exception is unhelpful. It doesn’t have the information we probably want. For example, you just might want to know, which key was already added as the following demonstrates:

items.GroupBy(item => item.Id)
    .ToDictionary(group => group.Key, group =>
    {
        try
        {
            return group.Single();
        }
        catch (InvalidOperationException)
        {
            throw new InvalidOperationException("Duplicate
  item with the key '" + group.First().Id + "'");
        }
    });

In this example, if a key has more than one element associated with it, we throw a more helpful exception message.

System.InvalidOperationException: Duplicate item with the
key '2'

In fact, we can encapsulate this into our own better extension method.

public static Dictionary<TKey, TSource>
  ToDictionaryBetter<TSource, TKey>(
    this IEnumerable<TSource> source,
    Func<TSource, TKey> keySelector)
{
  return source.GroupBy(keySelector)
    .ToDictionary(group => group.Key, group =>
    {
      try
      {
        return group.Single();
      }
      catch (InvalidOperationException)
      {
        throw new InvalidOperationException(
            string.Format("Duplicate item with the key
          '{0}'", keySelector(@group.First())));
      }
    });
}

Code mine mitigated!

This is just one example of a potential code mine that might go unnoticed during a code review if you’re not careful.

Now, when I review code and see a call to ToDictionary, I make a mental note to verify the assumption that the key selector must never lead to duplicates.

When I write such code, I’ll use one of the techniques I mentioned above to make my intentions more clear. Or I’ll embed my assumptions into the code with a debug assert that proves that the items cannot have a duplicate key. This makes it clear to the next reviewer that this code will not break for this reason. This code still might not open the hatch, but at least it won’t have a duplicate key exception.

If I search through my code, I will find many other examples of potential code mines. What are some examples that you can think of? What mines do you look for when reviewing code?

personal, empathy, parenting comments suggest edit

This post is a departure from my typical software related topics, but I think you’ll find parallels with management and dealing with software developers.

Parenting is a skill like any other – it can be improved (for some more than others, amirite?!).

Look, I’m not trying to claim I’m the world’s greatest dad. But I was given a coffee mug with that claim by my kids. I don’t mean to brag, but I’m pretty sure they did a quantitative exhaustive analysis of all dads before conferring that award to me because that’s just how I raised them. Right kids?!

But I digress.

When my son was still a very young toddler, my wife and I took advantage of a Microsoft benefit that paid for parenting classes (Many Microsoft employees who are parents have no idea this benefit exists). We attended a series on “Reflective Parenting.” It was an amazing learning experience that taught us this idea that parenting is a skill like any other.

It’s a strange conceit of many parents that because they can reproduce, that they suddenly are imbued with unassailable parenting skills.

As Richard Stallman once remarked, perhaps callously,

It doesn’t take special talents to reproduce—even plants can do it. On the other hand, contributing to a program like Emacs takes real skill. That is really something to be proud of.

It helps more people, too.

And you never have to clean up poo from an Emacs blowout!

He’s right about one part. Even plants can reproduce. But reproducing is the easy part. Plants can’t parent.

Parenting is a subject that trends towards being heavy on tradition. “If it was good enough for me, it’s good enough for my kids.” But that’s not how progress is made my friends.

Despite my megalomaniacal tendencies, I like to think I turned out ok so far. My parents did a pretty good job. Does that mean I can’t strive to do even better? It’s worth a try. So in this post, I’ll explore what SCIENCE brings to bear on the subject. It may seem weird to invoke science in a subject as personal and emotional as parenting. But the scientific method is effective, even on a personal scale.

xkcd-standback

Note that the focus here is on core principles and less on specifics. I’m not going to tell you to spank or not spank your child (because we know that’ll end in a shit storm debate).

This post will focus on principles to consider when making your own decisions about these things. Because in the end, if you are a parent, it is ultimately up to you what you do…within reason.

That’s one reason try to embrace the “no judging” philosophy towards other parents. Each parent has a different situation and different background. I may offer ideas that I think are helpful, but I won’t judge. Unless you tend to drive off with your five-week-old child on top of your car. I might judge just an teensy weensy bit then.

Lessons from Reflective Parenting

The about page for the Center of Reflective Parenting says it was founded…

..in response to groundbreaking research in child development and the study of the neurobiology of the developing mind showing that the single best way to positively impact the attachment relationship is to increase a parent’s capacity to reflect on their relationship with their child – to think about the meaning that underlies behavior.

There’s a lot of science and research underlying the core precepts of this approach. But when you hear it, it doesn’t sound academic at all. In fact, it sounds a lot like common sense.

There are three core lessons I took from the classes.

Empathy

The first is to work on developing empathy and understanding for your child. We learned a lot about what children are capable of developmentally at certain ages. For example, at very young ages, children aren’t very good at understanding cause and effect.

This allows you to develop more appropriate expectations and responses to the things your child may do. At some ages, you just can’t expect them to respond to reason, for example. (By their teenage years, they can respond to reason, they just choose not to. It’s different.)

Self Control

The second, and perhaps more important lesson for me personally, is that good parenting is more about controlling yourself than your child. This is because children reflect the behavior of their parents.

For example, we’ve all been there, in the car, with the kids loudly misbehaving, when a parent gets fed up, blows up, and screams at the kids. I’ve been there.

In that moment the parent is not disciplining. The parent is only momentarily making him or herself feel better. But this teaches the kids that the best way to handle a stressful situation is to lose your shit. Discipline comes from the calm moments when a parent is very considered and in control of his or her actions. Remember, kids don’t do what you tell them to do. They do as you do.

In such situations, the class taught us to attempt to empathize with what the children might be experiencing and base our actions on that. If we can’t help but to lose our temper, it’s OK to separate ourselves from the situation. For example, in extreme situations, you might pull over, step out of the car, and let the kids scream their heads off while you (out of earshot) calm your nerves.

Repairing

Now this last point is the most important lesson. Parents, we are going to fuck up. We’re going to do it royally. Accept it. Forgive yourself. And then repair the situation.

I’ve lost my shit plenty of times. I’m pretty sure I did it twice this past week. It doesn’t make me a bad parent, though I feel that way at the moment. What would make me a bad parent is if I doubled down on my anger and never apologized to the kids and never tried to repair whatever damage I may have caused.

Some parents believe in the doctrine of parental infallibility. Never let them see you sweat and never admit fault to your children lest they see an opening and walk all over you.

But when you consider the principle that kids do as you do, I don’t think this doctrine stands up to scrutiny. I hope you want your children to be able to admit when they were wrong and know how to deliver a sincere apology. Teach by living the example.

The Economist’s Guide to Parenting

Many years after the reflective parenting class, I listened to this outstanding Freakonomics Podcast epidsode on parenting.

I know what you’re thinking when you read the title of this podcast. You’re thinking what the **** — economists? What can economists possibly have to say about something as emotional, as nuanced, as humane, as parenting? Well, let me say this: because economists aren’t necessarily emotional (or, for that matter, all that nuanced or humane), maybe they’re exactly the people we need to sort this through. Maybe.

As you might expect, it’s hard to conduct a double blind laboratory study of raising kids. Are you going to separate twins at birth and knowingly give one to shitty parents and another to wonderful parents to examine the effects? Cool idea bro, but…

octopus-nope

But there are such things as natural experiments. There were studies done of large groups of twins separated at birth and raised by different adoptive parents.

The striking result of the studies is that what the parents did had very little influence in how kids ended up. Letting kids watch as much TV as they want? Restricting TV? Helicopter parenting? Piano and violin lessons? Sorry Tiger Mom, it made very little difference.

Over and over again, guess what made the difference. It wasn’t what the parents did, it’s who they were. Educated parents ended up with educated kids. As far as I could tell, the study didn’t really get into cause and effect much. For example, is it because educated parents tend to do the things that lead to educated kids? Inconclusive. But they did find that many of the practices of “helicopter parents” such as music lessons, etc. had very little affect on future success and happiness of the child.

But studies reveal there is one thing parents do that had a strong correlation with how their progeny end up - how parents treated wait staff. Those who were rude to waiters and waitresses ended up with rude children. Those who were kind and tipped well, ended up with kind kids.

See a pattern here?

Kids aren’t affected as much by what you tell them and what you teach them as much as what you do. If you’re curious and love learning, your kids are more likely to be infused with a similar passion for learning.

On one level, this is encouraging. You don’t need to schedule every hour of your children’s free time with Latin and theremin lessons for them to turn out well.

On the other hand, it’s also very challenging. If you’re a naturally awful misanthropic person it’s much harder to change yourself than to simply pay for classes.

I can be pretty lazy. But after the Freakonomics podcast, I started making an effort to do one simple thing every morning. Make the bed before I left the room. Honestly, I didn’t care so much if the bed was made, but I did like how a clean room made me feel less disheveled as I started my day.

And here’s the amazing thing. My son, who’s only five, will now sometimes come into the room to make our bed. I never asked him nor told him to. He saw me doing it and he’s reflecting my behavior. It’s really rather striking.

Go Forth And Parent

In the beginning I mentioned how parenting research applies to software developers. I wasn’t making a comparison of software developers to children (though if the description fits…). It’s more a comment on the idea that parenting is a lot like leadership. Like parents, leaders lead by doing, not by telling others what to do.

The good news is what you do as a parent has little effect on how your kids end up. The best thing you can do is focus on being the type of person you want your kids to be.

However, what you do in the interim can affect how well you cope with being a parent and all the travails that come with it. It also may affect what your relationship with your children will look like down the road. It’d kind of suck to raise wonderful successful kids who want nothing to do with you. So don’t be awful to them.

This is why I still think it’s worthwhile working on improving parenting skills. It’s less about affecting your kids success as adults and more about building a good lasting relationship with them.

Like any skill, there’s always new evidence coming in that might cause you to reevaluate how you parent. For example, here’s a list of ten things parents are often dead wrong about.

Perhaps you factor those in and maybe improve your technique. Maybe not. The key thing is, don’t sweat it too much. Ultimately, what we all want is for our kids to lead fulfilled and happy lives. This is one reason I optimize for my own happiness so they hopefully reflect that.

Happy parenting!

happiness