Tricky decisions… Code Contracts and Parallel Extensions in C# in Depth 2nd edition

I’d like some feedback from readers, and I suspect my blog is the simplest way to get it.

I’m currently writing chapter 15 of C# in Depth, tentatively about Code Contracts and Parallel Extensions. The problem is that I’m 15 pages in, and I haven’t finished Code Contracts yet. I suspect that with a typesetter moving the listings around a little it can be shortened a little bit, but I’m still concerned. With the amount I’ve still got to write, Code Contracts is going to end up at 20 pages and I expect Parallel Extensions may be 25. That makes for a pretty monstrous chapter for non-language features.

I’d like to present a few options:

  1. Keep going as I am, and take the hit of having a big chapter. I’m not going into huge amounts of detail anyway, but the bigger point is to demonstrate how code isn’t what it used to be. We’re no longer writing a simple series of statements to be executed in order. Code Contracts changes this dramatically with the binary rewriter, and Parallel Extensions adjusts the parallelism, and ironically makes it easier to write asynchronous code as if it were executed sequentially.
  2. Try to whittle the material down to my original target of around 35 pages. This means it’ll be a really cursory glance at each of the technologies – I’m unsure of how useful it would be at all at that point.
  3. Don’t even claim to give enough information to really get people going with the new technologies, but possibly introduce extra ones as well, such as PostSharp. Build the theme of "you’re not writing C# 1 any more" in a stronger sense – zoom back to show the bigger picture while ignoring the details.
  4. Separate them into different chapters. At this point half the new chapters would be non-language features, which isn’t great for the focus of the book… but at least they’d be a more reasonable size.
  5. Ditch the chapters from the book completely, possibly writing them as separate chapters to be available as a mini-ebook companion to the book. (We could possibly include them in the ebook version.) This would make the second edition more focused again and possibly give me a bit more space when revising earlier chapters. However, it does mean there’d only be two full-size new chapters for the second edition. (There’ll be a new "wrapping up" chapter as well for a sense of closure, but I’m not generally counting that.)

Other suggestions are welcome, of course. I’m not going to claim that we’ll end up doing whatever is suggested here, but I’m sure that popular opinion will influence the final decision.


83 thoughts on “Tricky decisions… Code Contracts and Parallel Extensions in C# in Depth 2nd edition”

  1. I would say by far going into the detail, even if the chapter becomes a bit longer is going to be the right way to go.

    The information I think will be very valuable as these topics are something that many people I’m quite sure will be looking to read more about.


  2. I like option 1. Although they aren’t directly language features, I think they are important to cover. Even if it increased the cost of the book, I would much rather buy one that covered this information in depth (at least somewhat) than not.


  3. As far as I know, focusing on the C# language has been the hallmark of C# in Depth. IMHO, if you think you’re going to mention things like PostSharp, you’re not on the right track. Whatever you do, try not to lose the focus on the language or the book will no longer be unique.


  4. I like option #4 the best. Even if they are not core language features, I think they are quite important, leaving them out, or covering them only in a superficial way would be rather unsatisfying.


  5. I’d vote for option 1.

    A larger-than-average chapter really doesn’t seem like a big deal, to me. I can only think of one technical book I’ve ever referenced where I remember that one chapter was unusually large, and that chapter was more than half of the 13 (or so) chapter book.


  6. I’d try to reframe it. You mention that you want to push the concept that we’re not writing C# 1 anymore. This could turn into a good narrative for that idea.

    With Parallel Extensions, you type things that are method invocations, but thanks to new language features and a deliberate style could be mistaken for language additions. With Code Contracts and its tooling, the specially formed code adds analysis and extra checking to the build process. And with PostSharp and its post-compilation rewriting, a language construct like attributes is actually supercharged to go places that it wouldn’t otherwise.

    Knowing you, you’ve already explained in detail how PFX and Code Contracts work, and you’ll have to cut some of it anyway (or include it and fear that you’re diluting the book’s original purpose). Just include the full explanation as an article on the companion site or someplace else. The three techniques are all plenty individually interesting to merit an article or a chapter; do what fits best with the rest of the book.


  7. With the title including “in Depth” you need to provide details. Anything less would be a disappointment. With that said, don’t bore me to death.

    A chapter of 50 pages is not hard to get through, so don’t even worry about that. If I feel that I won’t gain much value from a chapter in a technical book, then I skip it and come back to it later.

    I believe that option 4 may be the best. When the topic shifts after a while, a new chapter should be used to logically separate them, helping to signal the reader. And it certainly seems that you are getting detailed, and rightly so, into each topic, making them, indeed, separable.


  8. no 4.

    Let’s be honest – most people who will read your book will look for getting up to speed with .NET 4.0, so having bigger focus on new features, even non-language ones,even at the expense of slimming down early chapters would be good.


  9. Either option #1 or #4. I am sure more details are going to be appreciated by your readers.

    Do not worry about chapter length at all unless your publisher will put a limit on the size of the book, in such a case go with #5.


  10. I vote for option 1.

    More information is always better than less, and you have a way of explaining things that makes it easier to understand than other sources, so anyone in their right mind would rather read it from you than from, say, MSDN.

    I reviewed the original book, and really liked the flow of it, and I suspect it makes sense to make these chapters long, but you are balking because you don’t know how people will feel about it.

    I would ask if you have looked at Petzold’s WPF book. It doesn’t even have subtitles for the different sections w/i a chapter, but I read it anyway.

    Some people may skim the chapter or skip it altogether, but it will bring huge added value to those who are looking for and/or are interested in that subject.


  11. I would vote for option 5. I would rather want you to do justice to the topic instead of simply glancing at the topic. There are plenty of resources on the Internet to get a cursory glance at the topic, but I doubt I will be able to find the in depth discussion of these topics anywhere else.


  12. Thanks for the great comments, folks – keep them coming. I might have known there wouldn’t be a consensus :) Having said that, options 2 and 3 don’t seem to be popular. As 1 and 4 are pretty similar, it looks like it’s really a split between “keep it in, keep it detailed” and “get rid of it, put it in a PDF.”

    The good news is that those options basically involve a decision later on – I’ll write the same things anyway, pretty much.

    At the moment I’m tempted to keep it in and see what MEAP readers make of it – it’ll be easier to make an informed decision once you’ve seen the material. We’ll see what other comments come in though…



  13. Option #5 is the best IMHO (mini-ebook companion to the book). This will kill two birds with one stone – focusing on the C# language in the book and “in depth” covering other “not language” cool new features too in the mini-ebook.


  14. Either option 1 or 4. Go into as much detail as necessary, that’s what made the last edition so good. And please include PostSharp, I’ve always found it quite confusing.


  15. all the best books are clean in principle, the beauty of c# in depth is, it was just that. Rarely is there a better opportunity to make best use of the tools at your disposal than when you understand why the language evolved to include the features, and what problems the language features are there to solve. That in a nutshell, is why i loved c# in depth, all the most current (3.5) features make perfect sense and its clear why and when to use them. I fear that polluting the text with non language features would devalue what made it so great in the first place. C# in a nutshell is another good example of a book with a clear and conceise mission and almost perfect execution, its still the best reference out there, Terse and pragmatic. please keep the next edition of c# in depth the same. Surely there is scope for a “.Net framework in depth” within which the framework features you discussed would fit perfectly. On a separate note, i think AOP and DI are poorly catered for and could probably even merit their own text something along the lines of “contemporary development with .Net in Depth” following the same evolutionary approach to explaining in context why AOP, MVC frameworks and DI and the like are good, and why they are there, what problems they solve and when to use them..


  16. I would expect any detail on these features to be from the view of how it impacts C#. I don’t expect a fully detailed in-depth analysis of the features themselves. Save that for a PDF or a different book


  17. Option 4 seems to make the most sense.

    Though I think that’s more me wanting to learn about code contracts and parallel extensions from Jon and not necessarily because it actually has anything to do with C#. I personally think it would add value to the book for me.


  18. I’d have to say #4… or maybe #5. :)

    I wouldn’t be too pragmatic about the definition of the “C# *language*”. For example, I’ve heard many people state that C++ doesn’t have a string type. But it does – the C++ standard library is considered part of the C++ language specification.

    Now, technically, the C# language spec does not include a lot of the BCL. However, I’d say that libraries produced by Microsoft and included in the default .NET install could be considered “augments to the language” *if* they cause a significant shift to the way large amounts of code are written.

    Of course, this is a grey area. Code Contracts would *definitely* be a language augmentor. You could also possibly include the TraceListener support as an augmentor.

    Parallel Extensions I’m not quite as sure about. If it were me, I’d include them, but I have a prejudice towards asynchronous code. :)

    On the other hand, between Tasks and the Reactive Rx framework rumored to be included in 4.0, there’s a *lot* of ground being covered very quickly in that area.

    I would definitely say that (at least) Code Contracts should be considered part of the “C# 4.0 language”, conceptually if not technically.


  19. I’d go with option 1, but split up into logical 15.1, 15.2, 15.3, etc; with option 4 a close second.

    Maybe I don’t have the author/publisher perspective, but I can’t get excited about the physical **size** of the chapter.


  20. I vote for #3, and additionally include the Cecil framework, and STM.Net (released a few days ago) as language-enhancement framework.


  21. I know nothing about your target style, but the big chapter and split it into two chapters options seems like the best ideas to me.


  22. Are you writing “C# in Depth” or “.Net Framework in Depth”? If the latter, then surely you will be writing in depth about the many other important types in addition to code contracts and parallel extensions.

    Of course the above was rhetorical because I know that the focus is on C# as a language. And that is what I would expect from the book. So focus on the language and leave off-topic-filler fluff to dedicated books. The only real option is #5.


  23. Code Contracts: YES it deserves a verbose chapter and this is closely related to language. IMHO contracts should have been first class citizen of C#/VB.NET since the beginning :o/

    Parallel Extensions in C#: NO, your book is not a Fx book, it is a language book. Don’t tweak the spirit of your book.

    Please, explain DbC spirit in depth (see the kind of debate it can provoke):


  24. I think both topics are important and option 4 is the best to present those.

    Both topics deal with changes to the way you write C# code. Just as LINQ tries to get you to think in a more functional way, PLINQ extends this further so to me it is a progression fro what C# 3.0 does.

    The other topic that would seem to fit nicely into this mix is the recently announced STM.NET. Like both of the other topics, it was originally proposed as a set of language extensions, but is now going to be added to .NET 4.0 as a library.


  25. If the chapters provides nothing I couldn’t get from either the spec or the blurb then there’s no point going into detail.

    I you can go in depth and explain better the intricacies but that requires a longer chapter then I’m all for it. It’s not a quick reference book it’s for learning the complexities.

    I would say the parallel extensions have the most intrinsic subtleties since they take one paradigm (parallel) and make it superficially sequential. Code contracts are interesting but not so fundamental to my point of view.

    I definitely wouldn’t cover postsharp. If MS built an AOP framework themselves fine but it’s not sufficiently widespread for me to care.


  26. My view is that if it’s a feature that (a) could easily have been a language feature. (and is in some languages) and (b) is of broad enough importance that all c# developers should at least be aware of it, then it belongs under the banner of “C# In Depth”.

    I believe that applies to both features – but especally code contracts.

    My preference would be for both features to receive full coverage, in their own chapters – all within a section that introduces the concept of extra-linguical (is that the right word?) features, and concluding with a small chapter that talks about other cool ways the language can be extended with AOP, DI, and others. I think PostSharp deserves a mention in that chapter.


  27. Jon,

    I vote for option #4. I believe that these topics are important enough to merit coverage in your book, but that they should receive separate chapers (separation of concerns isn’t just a great programming concept).

    Best wishes,



  28. Please do continue as you are going.. I wouldn’t mind reading an additional 10 pages on Code Contracts as long as the matter is helpful.

    I am not so sure about parallel extensions though..


  29. My vote goes to option 4 is you promise to keep the level of detail of option 1 in both chapters :)

    As the next version of C# doesn’t seem to be as overwhelming as the two previous versions, I would like to see detailed coverage of contracts as this will probably have a big impact on the way we use C#.


  30. I agree with Phil Nash, those two are technically library features but they are on the same level as true language features insofar as they are generally useful and not tied to any specific usage scenario. I say keep the chapter but split it in two if it gets too big.


  31. I’d suggest option 1, where option 3 is a close second.

    I think you should put as much information about the new technologies in as you fill its needed, and don’t worry about the chapter’s length. If they really do get huge, then option 3 does seem better.

    Either way I think that discarding details about the new technologies is the wrong way to go.


  32. I would go for option 1 – understanding of the wider thoughts on the language is the books selling point to me – in v1 you went all the way back to c#1 c#2 to explain 3. If there are areas that you need to bring in to help understand then it seems in keeping with the ethos of in depth.

    Parallel is going to be a big growth area and understanding that is going to be key to the book longetvity.


  33. Another vote for #4 here, with #1 as a back up. Making stuff available in electronic form as in #5 is all well and good, but the thing about books is that they can easily be read in places that you can’t easily use a computer, such as standing up on the train when commuting to work or in the bog etc. eBooks can work on handheld devices like an iPhone etc, but whilst this might be fine for a novel it often doesn’t work well for technical stuff where there may be diagrams or formatted code examples etc that don’t work on tiny screens.

    If publishing constraints make 1 and 4 un-workable then at least go with 2 or 3 so that some of these things are introduced in the book. Yep the information may be available elsewhere, but as someone who isn’t following the work on .net 4 / c# 4 your book is likely to be my first introduction to all of this stuff, so knowing a little bit about what is out there will be valuable even if I then have to go and find further material about it.


  34. I suggest #4 too.

    Why are code contracts and parallels extensions treated in the same chapter anyway? The relation between them is too vague to make a full chapter with both topics.

    Chapters are easy to skip so that if I want to read about Parallels Extensions I will be able to without having to search through code contracts that might not interest me at all.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s