Archive for November, 2013

Instant Nancy Web Development – A book review

Wednesday, November 27th, 2013

I got an email a couple of weeks back from the publisher of “Instant Nancy Web Development” (by Christian Horsdal (@chr_horsdal) asking if I’d review a new book they were publishing on Nancy web development.

It didn’t pique my interest, not because of the subject matter, but because of the horror stories I’d seen around the web regarding both the quality of their books along with the way they treat their authors and reviewers.

I first became aware of Packt when they got into the habit of asking me to both work for free (sorry, for the pleasure of seeing my name in print) or occasionally to write books about things that I only had a passing grasp of.

Suffice to say, getting yet another email asking me to work for the reward of “a £7 eBook” isn’t normally the start of a pleasant experience, but this time it was a topic particularly close to my heart. Regardless, consider this full disclosure – I’m also fairly sure this isn’t the introduction their marketing department was hoping for. Good material rises to the top naturally, and I oppose this kind of paid-for marketing.

I like Nancy as a framework, and adopted fairly early in its life for real software (I’ve gone into that in detail previously) – I use it about as much as I use ASP.NET MVC, and I know it pretty well. I’m no expert, but I’ve used it a fair bit in anger. With that said, I’m not this books target audience. I went in having already read @philliphaydon‘s review, so I had a little context, and I cut through it in two sittings.

Firstly, the good – I enjoyed the tone of the book, it felt approachable and light, pitching itself as a getting started guide. The preface is decent at explaining why Nancy exists, though suffers a little from waffle and repetition – though no more so than other first books.

The structure is approachable, each chapter dealing with a single recipe with code and tests shown along with the downloads, and for the most part the examples are clear and easy to follow.

There are a couple of especially good examples that are worth calling out – custom accept types and content negotiation (where I learnt things I’d not run into before) and the section about enabling Razor views were especially well baked.

Each chapter builds on the last and the author explains the progression between them clearly. As a series of examples that you can build on, A+, would recommend.

The bad – the focus on examples is a little bit of a double edged sword really. The book reads like a well thought out series of blog posts, but lacks a sense of narrative or direction. Reading through it, I couldn’t help but feel that at no point had the general anatomy of a Nancy app really been explained.

Concepts are introduced and reinforced with examples, but you’re expected to pick up the why on the way. As a result, when the book does start pushing test first development (which is obviously a good thing) or dependency injection, it feels out of place from the steady canter of test example, test example. Notably, at one point the book spends a couple of paragraphs discussing testing on AppHarbour, which felt like a total tangent at the time, coupled with the logging example featuring especially verbose tests and delving a little too deeply into NLog.

There were also a couple of things I picked up in the examples that’d probably cause issue – copying views to output locations is a gotcha if you want to quickly host your existing app in IIS, and the default self host example neglects to point out that you can have Nancy do URL reservation rather than shelling out to the command line.

If anything, this is a book that feels like it wanted to be bigger than it ended up. There’s good narrative material on TDD, logging and explaining the need for Nancy, but it just felt like it was missing the cohesion and guidance to hold it together as more than a rock solid set of examples. If there were to be a second edition, I’d love to see the author share more about how he prefers to structure applications that use Nancy, rather than just focusing on “what works”.

The ugly – Kindle formatting. I read though the book on a Nexus 7 with the Kindle app, and the formatting for tablets is a bit of a mess. Formatting code is never going to be pretty on eReaders, and the code itself is no better or worse than other technical books, but I spent a couple of minutes confused during the introduction that explained that attention would be called to specific areas of the code using bold. Which looked exactly like regular text to me. I suspect I’d have a better experience reading the PDF, but you live and learn.

An aside – should this book not be a pull request? Reading through, I couldn’t help feeling like I was reading a more awesome version of the official Nancy documentation. Nancy is open source, and community built, and while holding my £7 eBook, I repeatedly found myself feeling that “this would make a much better default example that the example on the GitHub wiki”. It’d be interesting to see if this book, or its examples could somehow be merged and canonised – and grown by the community much in the spirit of the framework itself. I have no issue with people being paid for work, or spending time writing something to sell, but the focus on recipes here just felt almost too much like “the awesome documentation people don’t quite have time to write”.

Conclusion – Well, firstly, I’m glad this book exists and I enjoyed reading it and can recommend it. It’s a solid first book, and manages to make that leap from “blog series to book” decently. It’s short enough to not be intimidating, it’s friendly and especially suited to beginners, and is another avenue to promote a great open source framework to people who perhaps would discount something as being “not quite ready” if all they had available were wiki pages. It reads well, you’ll learn something, and if you want a quick 0-60 into the “how” of building applications with Nancy, it’ll suit you well. If you’re looking for the “why”, you might be left wanting.

Using build failure conditions in TeamCity to ensure "improving" test coverage in .NET apps

Monday, November 18th, 2013

All code that wasn’t written yesterday is legacy code. We all have it, and it’s important that we give it the love and attention it deserves. TeamCity (my favourite CI server, gun-against-head) lets you run code coverage metrics on your code-base using it’s own bundled install of dotCover – pretty common knowledge – but another thing it’ll do is allow you to make your build fail if your code coverage decreases “build on build”.

What this feature does, is track the coverage level of your “last successful build” vs. your current one, meaning you can make your build fail if you inadvertently reduce the level of coverage in your code-base. It’s a nice way to introduce toxicity reports / tests to browner-field apps, as it doesn’t mandate “THOU SHALT HAVE 90% COVERAGE” but instead, focuses on “improving” metrics over time. This kind of code sanitation is most valuable in brown-field apps where retrofitting testability hasn’t been the top priority – basically forcing build failures if you make crappy code crappier.

image

You can configure your project to do this by adding three build failure conditions, then add three metrics (percent of method coverage is less than 0.% compared to last successful build, percent of class coverage is less than 0.% compared to last successful build, percent of statement coverage is less than 0.% compared to last successful build) that “fail build on metric change” – the 0.5% threshold is good enough to cope with rounding errors or glitches, while maintaining that any new code that gets added, gets tested.

It’s a no brainer, and hopefully will stop you introducing regressions because something is “too hard” to test.

Announcing: System.Configuration.Abstractions

Wednesday, November 6th, 2013

What is it?

In most projects, you’re going to have some configuration. In .NET projects, it’ll probably start in your app.config or web.config file.

However, if you love TDD, you’ll likely have notice that all of the built in configuration classes are horribly un-testable. They all revolve around static references to System.Configuration.ConfigurationManager, and don’t really have any interfaces, so in every project, you end up wrapping them into something like “IAppSettingsWrapper”, in order to write tests.

After writing these wrappers what seems like hundreds of times, and being inspired by the excellent System.IO.Abstractions package, I’ve put together a standardised set of wrappers around these core framework classes.

Why Do I Need It?

* Want to mock/stub/whatever out your App/Web.config files?
* Want to assert that the values from configuration are *really* configuring your application?
* Want to add custom hooks around loading configuration values?
* Want stronger typing?

This is for you.

Where do I get it?

From source: https://github.com/davidwhitney/System.Configuration.Abstractions
By hand: https://www.nuget.org/packages/System.Configuration.Abstractions

NuGet:

        PM> Install-Package System.Configuration.Abstractions

Anything else?

I’ve also baked in a few strongly typed helpers to make your code a little less crufty (no more Int32.TryParse’ing your way to victory) along with a strong convention for “ConfigurationInterceptors” in case you’d like to hook in and add code around configuration reading.

Hopefully it’ll make your life just a little bit easier. More details in the readme on GitHub.

Writing great user stories

Wednesday, November 6th, 2013

When you’re building software, defining “what” you’re going to build is as vital as how you’re going to do it. A couple of months ago I put together this deck on writing user stories – hopefully it’ll help you through the more human side of building great software.