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

    Like

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

    Like

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

    Like

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

    Like

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

    Like

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

    Like

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

    Like

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

    Like

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

    Like

  10. 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 ;)

    Like

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

    Like

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

    Like

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

    Like

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

    Like

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

    Like

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

    Like

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

    Like

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

    Like

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

    Like

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

    Like

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

    Like

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s