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.

Thoughts?

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. Either 1 or 4 are fine with me. The more detail that can be provided in such a great book, the better.

  12. 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.

  13. 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…

    Jon

  14. 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.

  15. 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.

  16. 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..

  17. 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

  18. 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.

  19. 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.

  20. 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.

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

  22. 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.

  23. 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.

  24. 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):
    http://codebetter.com/blogs/patricksmacchia/archive/2009/05/17/book-review-code-leader-by-patrick-cauldwell-a-digression-on-contracts.aspx

  25. 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.

  26. 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.

  27. 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.

  28. 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,

    Jason

  29. 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..

  30. 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#.

  31. 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.

  32. 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.

  33. 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.

  34. 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.

  35. 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.

  36. #3 or #5 — Code Contracts and Parallel Extensions are not language features, too big to fit into one chapter each, and if you want to convey the idea of “your C# is not simple C# anymore” why not explain why this is so and why this idea is important instead of getting into details on specific libraries.

  37. I vote 1 or 4. I’m not going to judge a book by putting each chapter into a language or non-language bucket.

    I like books that cover their core topic in depth but also introduce a number of peripheral topics to add some breadth. I find it much easier to learn new topics first by reading about the basics then hitting up other detailed sources for in depth knowledge.

    If you drop those chapters then I as a reader don’t know what I don’t know (assuming I only read this book and nothing else). But if you keep those topics then at least I will know what I don’t know: specifically I will know that contracts and parallel extensions exist and be able to decide if I should learn more and apply it to my own projects.

  38. Just adding to my earlier 4 or 1 vote, this book is to be a second edition, with the most obvious changes to the first detailing what version 4 adds over version 3. Given the base structure of the original edition (here’s c#1, this is what 2 then 3 add to it) for those of us who already own the first edition having extra chapters makes it a more compelling purchase as there is extra added value that will leap out from the contents page.

  39. I’d gotta vote for #5 here. It’s not a language feature. Stick to the focus of the chapters, and allow people who don’t want to read about non-language features to experience the thrill of actually finishing a technical book in it’s entirety. Besides, it sounds like there might potentially be enough info here for a completely separate book to begin with.

    I don’t like the mini-book idea or the “only available in e-book” idea. People who purchase the print copy should get the same experience as those who purchase the ebook, plain and simple. Print versus electronic is simply a preference. If you’re going to include it, include it in both.

  40. I like #1 best … Contracts are VERY important and deserve full and detailed coverage we look for from from you! The fact Contracts are implemented in a way that all languages can take advantage of is a good thing .. and the reality is a book about C# programming is in reality (at least to a certain extent a book about .Net programming) … Contracts ( and Parallel Extensions too) are a .Net programming thing.

    Personally, this weekend I’m going to buy the MEAP ebook version so #5 has appeal too.

  41. One other point … I wholeheartedly agree with Stephen Cleary above that PFX and Rx (when it comes out) deserve coverage. CCR might be the most promising of them all!

    One of these is sure to build some momentum among developers. I certainly intend to wait an see how things play out.

    kf

  42. I’m adding my vote for #5.

    From the MSDN: “Code Contracts provide a language-agnostic way to express coding assumptions in .NET programs”.
    What else needs to be said?

    New .NET 4 features make for great topics, but since they are not language-specific it makes sense to keep them separate so that the non-C# folks out there might benefit from that information too.

  43. As the code contracts and parallel stuff are .NET (language agnostic), the material you present may be of great value to VB.NET programmers (and any other suitable language).

    So I’d prefer to see that material in a separate book altogether – you could get a VB.NET person to provide the equivalent VB.NET example code for each snippet, maybe, to broaden its appeal.

    I say keep the C# book about things that are specific to C#; though by all means present a quick sweep through these to get across the idea of the blurring of the boundary between language/library constructs in modern development styles.

  44. Adding a vote for 5. I’m not big into C#, but I buy the in-depth books because I want the detailed stuff.

    The problem with dead trees vs. the rich web publications that are starting to become standard for documentation in the open-source world is that rich web docs can link to in-depth discussions of various topics, wikipedia articles, code examples, etc.

    I’d really like to see a big bunch of companion documentation on a CD that comes with the dead trees version; I’d also be much more likely to buy an eBook version with the links inline already.

  45. I’d vote for option 2, then add footnotes on where we can find more information about the subject if we want to study it further. Just make sure that all the essential stuff are in those 35 pages ;)

  46. I stopped getting influenced by the chapter boundaries soon after I completed my graduation. Now the content is more important than the fact whether it is in same chapter or different one.

    By the way, I am in the process of reading the first edition of book. I must say it is really ** in depth**! I am having hard time digesting it. But it is fun! Good luck…

  47. I like options #1 and #4.

    For option #4: you could also include the two topics at the end of the book as appendix/addendum, as a sort of a “gift for the reader”. This way you could also speak about PostSharp and/or other things, avoiding “tricky decisions”.

    PS: … can’t wait for the new edition of your book. Great job!

  48. Like the rest options 1 or 4.

    Initally i’d lean to option 4 if there is going to be a hell of a lot there. I suppose when you’ve finished writing it, you can play around with both to see what fits best with the book.

  49. You don’t need to cover how to design contracts, you do need to describe how to state them in C# source (I assume it uses attributes). Some information on the weaknesses of the C# type system that make an external contract library necessary would be a better fit for a language book than a tutorial on contracts (and if you do the latter, discussing the C# type system is a necessity for your target audience). A couple examples of “the compiler can’t save you from this mistake” with unannotated and contract annotated versions of the code and the tie back to the formal type system (e.g. being readonly is not a possible property of references in .NET like it is in other languages) should be enough to sell people on contracts and send them looking for further resources. I think full coverage of the topic would require a whole book anyway.

  50. Okay first of all I have a biased view as my book is an overview of the new stuff in .net 4/vs2010.

    For me the great and unique thing about your original book was the depth and focus. No other book really goes into the same level of detail and this keeps me referring back to it.

    In my opionion Code contracts deserves its own chapter although I guess I wouldnt expect to find out about PFX from your book.

    Ideas such as Post Sharp are interesting could change the way we develop applications and are worth a mention but not there own chapter.

    Enjoying the MEAP chapters I have read so far :)

  51. #5 for me.

    I already bought the book and I would love to get those 50 pages for free. However, I think the book should keep its language oriented uniqueness, and avoid becoming too fat. I realy liked the first edition to be less than 400 pages.

  52. Option 4 for me.. I would rather have a fat book with lots of detail than have to read from the screen.

  53. Option one or option four, or put the chapter(s) in an appendix. I think that the mention/introduction/detail on these two features will be appreciated.

  54. As other’s have said, I think your best option here is to do a Tolkien and have a couple of healthy appendices.

    A troll and a wizard would be cool too, but that’s your call.

  55. Hi, I hope that you go for the large big chapter :-) Those are two of the topics which interest me most, and I think that I’m not alone…

  56. Oh well – I’ll throw my opinion in as well… I vote #1

    I haven’t really had a good look at C#4 yet(*) but the two things I’m really interested in learning are Code Contracts and Parallel Extensions, so the more detail you can provide the better :)

    (*) We’re still using .net 2.0. We were moving to 3.5 but we’re now looking at jumping straight to 4.

  57. I think you should include Code Contracts in detail as ALL c# programmers should be able to at least read them. They will be come part of the standard documentation for 3rd party code.

    However you should only cover the Code Contract tools that normal C# programmers will have access to. E.g If a tool is only in the team edition of developer studio, don’t spend match time on it.

    However I don’t think you should cover Parallel Extensions, as parallel programmer is not someone that most C# programmers have to do and it needs a book in it’s own right.

Comments are closed.