Tag: Example Code

Working with Code in e-Books

This is an update of a post that originally appeared on March 16, 2016.

Most of my technical readers now use e-books instead of paper books. Of course, there is a convenience factor to storing your entire library on a Kindle, even if it’s a software version of the Kindle. Of course, there are all sorts of e-book formats for your desktop system as well. The point is that electronic format makes a lot of sense when dealing with technical books.

However, e-books can cause some interesting problems and I’ve encountered a few with a number of readers now. The most important consideration is that you can’t cut and paste code from an e-book directly into your IDE and expect it to work. There are all sorts of reasons for this exclusion. For example, cutting and pasting may insert special characters into the output stream or the resulting paste may not have white space in the right places. A common problem is that publishers often convert regular single and double quotes into curly quote equivalents. The two kinds of quotes (both single and double) are completely different and the second type definitely won’t compile.

The best option when working with an e-book is to view the code in the e-book, but still get the downloadable source code for the book from my website or the publisher’s website as described in the book’s introduction. If you can’t find the downloadable source, always feel free to contact me at [email protected]. I want to be sure you have a great reading experience, which means having source code that actually runs in your development environment.

Another potential problem with e-books is that you may see unfortunate code breaks (despite the efforts of the publisher and myself). When you need to understand how white space works with a programming language, always review the downloadable source. The fact that the downloadable source compiles and runs tells you that all the of white space is in the right place and of the correct type. Typing the source code directly out of your e-book could result in added carriage returns or other white space errors that will cause the code to fail, even though the commands, variables, and other parts of the code are all correct.

As always, I’m open to your questions about my books. If you don’t understand how things work, please contact me—that’s why I’m here.

Choosing an Example Type

It can be difficult to choose just the right kind of source code examples to include in my books. In fact, readers often write to ask why I didn’t choose a different kind of example for a book. For example, a lot of readers tend to prefer console applications because they’re:

 

  • Straightforward
  • Easy to understand
  • Easy to write
  • Demonstrate the code clearly
  • Don’t rely on any automation


Given these reasons, it would seem as if I’d use console applications for all of my examples in all of my books. In fact, these benefits (and others) are the reason I used console applications in C++ All-In-One Desk Reference For Dummies. In fact, to this list, you can add the benefit of the same example code running on multiple platforms to the list. The same example code runs on Mac, Linux, and Windows platforms with the GCC compiler. Even with this book, however, I’ve had readers write to ask why I didn’t use a different compiler or IDE and why I didn’t include examples that demonstrate the ability to use C++ to create user interfaces in anything but Visual Studio (the new edition of the book won’t include the Visual Studio examples).

Some books don’t lend themselves to console applications. For example, one of the purposes of Microsoft ADO.NET Entity Framework Step by Step is to show how you can use the automation provided by Visual Studio to write your applications with less code and in significantly less time. Not everyone likes the automation and I’ve actually had a few readers ask why I couldn’t write the examples using a console application format. The problem is that few people use the Entity Framework with console applications and the automation is there to simplify things. I understand that other books may provide console application examples, but I chose to provide the examples in a form that the majority of my readers would use in a real world setting.

Trying to come up with a book that pleases everyone is simply impossible because everyone has different needs. It all comes down to people wanting the best deal possible in a book, which means seeing an example that uses their environment on their platform and demonstrating precisely the kind of code they need to write. It’s an unrealistic expectation for any book. My Getting the Most from Your Technical Reading Experience post explains how you can optimize the purchasing experience to obtain the best book for your needs. The caveat is that no matter how good the purchase is, the book will never answer all of your questions and most definitely won’t answer them in precisely the way you need them answered for fulfill an application development requirement.

Of course, I’m always open to your input. It’s the reason I run this blog and ask for your input in nearly every post. My purpose in writing is to answer as many questions as I can for as many readers as I can in the best way possible. Sometimes that means I need to take a step back and rethink a particular process I’m using, technique I’m applying, or perspective I’m pursuing. I encourage you to continue contacting me at [email protected] with your book-related queries. I always use your input to help create better books in the future.