Verifying Your Hand Typed Code

I maintain statistics for each of my books that are based on reviews and reader e-mails (so those e-mails you send really are important). These statistics help me write better books in the future and also help me determine the sorts of topics I need to address in my blog. It turns out that one of the most commonly asked questions is why a reader’s hand typed code doesn’t work. Some readers simply ask the question without giving me any details at all, which makes the question impossible to answer. In some cases, the reader sends the hand typed code, expecting that I’ll take time to troubleshoot it. However, this isn’t a realistic request because it defeats the very purpose behind typing the code by hand. If I take the time to diagnose the problems in the code you typed, I’ll be the one to learn an interesting lesson, not you. If you learn better by doing—that is, by typing the code by hand and then running it, then you need to be the one to troubleshoot any problems with the resulting code.

My advice to readers is to use the downloadable source code when working through the book text. If you want to type the code by hand after that as part of your learning experience, at least you’ll know that the example works on your system and you’ll also understand how the example works well enough to troubleshoot any errors in your own code. However, you need to be the one to diagnose the errors. If nothing else, perform a character-by-character comparison of your code to the example code that you downloaded from the publisher’s site. Often, a reader will write back after I suggest this approach and mention that they had no idea that a particular special symbol or method of formatting content was important. These are the sorts of lessons that this kind of exercise provide.

Now, it has happened that the downloadable source code doesn’t always work on a particular user’s system. When the error is in the code or something I can determine about the coding environment, you can be certain that I’ll post information about it on my blog. This should be the first place you look for such information. Simply click on the book title in question under the Technical category. You’ll find a list of posts for that book. Always feel free to contact me about a book-specific question. I want to be sure you have a good learning experience.

There are some situations where a reader tries to run application code that won’t work on a particular system. My books provide information on the kind of system you should use, but I can’t always determine exceptions to the rule in advance. When I post system requirements, your system must meet those requirements because the examples are guaranteed to fail on lesser systems. If you encounter a situation where the downloadable code won’t run on your system, but none of the fixes I post for that code work and your system does meet the requirements, then please feel free to contact me. There are times where an example simply won’t run because you can’t use the required software or the system won’t support it for whatever reason.

The point of this post is that you need to work with the downloadable source code whenever possible. The downloadable source code has been tested by a number of people, usually on a range of systems, to ensure it will work on your system too. I understand that typing the code by hand is an important and viable way to learn, but you should reserve this method as the second learning tier—used after you have tried the downloadable source code. Please let me know if you have any questions or concerns at John@JohnMuellerBooks.com.

 

Source Code Support

Sometimes I need to make really tough decisions.  It isn’t a matter of wanting to make the decision—the need to make the decision is thrust upon me. The topic of this post is source code support in the form of reader uploads. The topic of just how far I need to support book source code has come up before in conversations with readers. For example, in the Source Code Download Issues post, I discuss problems that readers have had in obtaining source code for my books in the past. The issue addressed in this post is files that are removed from archive (.ZIP) files by applications such as firewalls. In some rare cases, files are missing from the download and the reader looks to me to solve the problem. A few readers have gone so far as to say that I really need to provide CDs with the source code on them and mail those disks out free of charge as part of supporting the book. Unfortunately, supporting the books in this way is well beyond my ability. I could easily go bankrupt providing this level of support.

Up until now, I’ve been willing to send source code to a reader who needs it using e-mail unless the book is on my unsupported list. This past month has been especially hectic with reader requests for source code uploads (well over a hundred of them). In some cases, the books in question are ten or more years old, which means I must look the book up in my archives and determine whether the source code is even available. Once I make that determination, I copy the source from the archive and send it to the reader in one or more e-mails. Some of the source code files are 20 MB or so in size and many reader e-mail accounts won’t accept a file that size, so I have to break the file down into pieces and send multiple e-mails to the reader—a time-consuming and error prone task. This past week I went through several problematic uploads and finally gave up trying to support the reader in a number of cases. Nothing I would do would allow the reader to receive the file using e-mail.

I’ve thought about making the source available on my Web site, but that approach hasn’t worked well in the past because readers will often complain they can’t find the source or that the source on the Web site is corrupted (or any number of other issues). Of course, there are also costs associated with online storage for source code for 89 books. After a lot of thought, I have decided that trying to support a book’s source code in this manner won’t work either.

With this in mind, I’ve decided that you’ll need to rely on the publisher’s site for downloading any source code associated with a book, unless the publisher provides a CD for the book. If there is a source code CD, then you need to follow the procedure described in my Obtaining Replacements for Broken Media post to obtain a new CD. I didn’t come to this decision easily because I prefer to provide the fullest possible level of support for my books whenever possible. The issue is the time required to provide the support. On some days it has gotten to the point where a good part of my day is spent looking for resources that readers need and not getting much else accomplished.

When a publisher decides that it’s no longer feasible to provide download support for a book, the source code for that book will become unavailable. In fact, I’ll likely add the book to my unsupported list. It wasn’t an easy decision, but I had to make it because the e-mail support has gotten to the point of affecting the support I can provide to readers for other needs. Please let me know about any concerns you have about this new policy at John@JohnMuellerBooks.com. If someone has a really good solution for this problem—one in which I can provide long term source code support without incurring huge monetary or time issues, I’ll provide an updated post. Thank you for your continued support of my books.

 

Web Service Examples in Books

A number of my books include Web service examples. It’s hard to write a book about any sort of development today and not include one or two Web service examples in it. In fact, some of my books, such as Start Here! Learn Microsoft Visual C# 2010 Programming contain a number of these examples. The reason is simple. Online services provide access to a wealth of information and can also reduce the programming burden on developers. Learning to use Web services provides a significant competitive advantage, so I need to discuss them in my books.

Creating a useful and interesting Web service example in a book is a lot harder than you might think. It’s not as if my book is for a particular kind of reader or someone who is looking for a specific type of information. In addition, I need to consider the overall learning experience that the reader will receive from the example. With these criteria in mind, I ask myself the following questions when choosing a Web service for a book.

 

  • Is the service free?
  • Is it general enough to be appealing to my reader?
  • Will the service be around tomorrow so that the reader doesn’t find a blank site?
  • Does the service include a well-designed API that will make it easy for my reader to learn?
  • Will the service be easy enough to use that the examples won’t become too complex?


There are often other questions I must ask, but you get the general idea from these questions. It isn’t simply a matter of choosing something, anything, online. Even though I’m particular about which Web service I choose, readers often encounter problems. Just this past week at least one reader complained about the REST example in Chapter 6 of Start Here! Learn Microsoft Visual C# 2010. It was a frustrating problem to troubleshoot because the example continued to work just fine for me. However, here are some things to consider when working through the Web service examples in one of my books:

 

  • Use the book’s source code, rather than type the source in yourself.
  • Look on my blog for updates for your book that show how to use any Web service updates.
  • Check your Internet connection to ensure it’s active.
  • Verify that the Web service is actually functional (and try back a few times, just in case).
  • Contact the Web service owner with questions you have about it.
  • Contact me at John@JohnMuellerBooks.com about example code that you simply can’t get to work.


I want you to have a great experience using my books. When I do encounter a Web service that has changed or is no longer in service (it does happen), I’ll try to update my example code so you can continue using the book, as long as the book is still supported (please check the unsupported book list on my Web site).

 

Finding the Source Code for Start Here! Learning Microsoft Visual C# 2010 Programming

A number of people have written to say that they can’t find the source code for my book, “Start Here! Learn Microsoft Visual C# 2010 Programming.” As I discussed in my Source Code Download Issues post, it’s really important that you download the source code for my books to ensure you have the best possible chance of a great learning experience. You can find the source code for this book at:

http://go.microsoft.com/FWLink/?Linkid=229177

If you experience any problem finding the site or downloading the code, please be sure to let me know. I’ll do whatever I can to ensure you get the source code you need to use the book productively.

In addition, make sure you let me know about any coding problems you experience. Yes, the examples are just that—examples. That means they don’t include error trapping found in a production application in many situations. If you type something weird, the application is most likely going to fail in an unexpected manner because it doesn’t contain the error trapping required to make it more robust. The error trapping is often left out for the sake of clarity, so that you can better understand the basis for the example. However, the code should still work well enough that you get the full benefit of working with it as you learn how to program in C#.

Of course, any code, even code in books, can contain errors and I always want a chance to alert you to those errors (along with the fixes to go with them). The best way for me to discover those errors and to be able to provide you with fixes is if you tell me about the problem. As with my other books, I’ll usually upload the fixes right here, so make sure you keep your eyes peeled for additions to the blog entries for this book.

Let me know about this and any other book-specific issue at John@JohnMuellerBooks.com. I’m always interested in hearing from you about issues that make my books less helpful than they could be.

 

Obtaining Replacements for Broken Media

A number of my books, including C++ All-In-One Desk Reference For Dummies and Java eLearning Kit for Dummies, come with some sort of media. As hard as the publishers try, it isn’t always possible to ensure that you receive this media in pristine condition. If you’re buying the book at a bookstore, make sure you check the media before you check out and get another copy of the book if you find that it’s broken (make sure the bookstore staff know that the media is broken so they can return the book for another copy).

With the demise of the larger bookstores, most of my readers are buying their books online today, which means you can’t look at the media when you’re browsing the shelves. If you buy from Amazon, make sure you return the book and get a new copy and let them know that the reason for the return is the broken media. Amazon will send you a new copy and they’ll return the copy with the broken media to the publisher.

Unfortunately, the book vendor may not always be very helpful or you might get the book as a gift and not be able to easily return it. In these situations, contact the publisher for a replacement. For example, if you have one of my Dummies books that includes media, you can contact the publisher, Wiley, at http://dummies.custhelp.com/app/ask/ for a replacement.

You know that I make it a top priority to help my readers with book-related whenever I can. In fact, the major purpose of the Technical category of this blog is to provide you with better service. This is unfortunately, one of the few situations where I can’t provide you with assistance, no matter how much I’d like to do so. I don’t have the resources required to create copies of the media for you and send it your way. If you do encounter problems reaching the publisher, please let me know and I’ll be more than happy to try to help you. As always, contact me at John@JohnMuellerBooks.com with any thoughts or concerns.

 

Source Code Download Issues

Most of my books include source code. The source code is made available on the publisher’s Web site and you download it from there. I always recommend downloading the source code to reduce the potential for errors. Typos are the number one source of problems for readers who work with the source code in my books. A single mistyped word will cause the application to fail in some way. If the reader is lucky, the compiler will catch the error and provide a clear message saying what’s wrong (such as the fact that the .ResX file is missing), but often that isn’t the case and then the reader becomes frustrated with the unworkable code. Sometimes the error isn’t even the reader’s fault—errors do creep into books (see my Errors in Writing post for details). The point is to use the fully tested downloadable source code whenever possible to save yourself time and effort.

 

There is another good incentive to download the source code. The reason to work through the source code in your debugger is to discover how it works through actual tracing. To help accomplish this task, the source code examples are carefully crafted to provide an optimal learning experience and they include features such as additional comments to help enhance the learning experience (see my Handling Source Code in Books post for details).


However, what happens when the downloaded source doesn’t appear to work either? Some readers have complained that the downloaded example won’t compile. Normally, the problem is one of a missing file. Firewalls and other network security features can strip out files and some organizations are proactive about stripping out anything that even looks binary. Consequently, the downloaded ZIP containing the source code is missing solution (.SLN), project (.CSProj or .VBProj), resource (.ResX), or other files. The project won’t compile with missing files. The best course of action is to try to download the source code from another systemone that isn’t inhibited by the network security features that stripped out the files.

 

Missing .DLL files aren’t normally an indication of a failed download. In most cases, missing .DLL files are part of a library or third party product you must install. The book will always include instructions on where to obtain these required add-ons and how to install them. Make sure you install any required additions as part of your system setup.


Sometimes a reader doesn’t have another way to download the file. Asking me to send the source code to you won’t help because the same features that strip out the files from the publisher site will also strip them out of the e-mail I send containing the files. In most cases, the firewall still downloads the actual source code. Create the project using the instructions from the book, and then copy and paste the source from the downloaded files into this new project. It’s not a perfect solution, but it should still work better (and faster) than typing all of the source code by hand.

A few readers have asked that I create a disk containing the source code and mail it to them. I’m not set up to perform this kind of support and the costs would be prohibitive. Unfortunately, if all else fails, you may have to try typing the source in by hand, but it should be your last option because typos really can ruin the learning experience. I’m always open to suggestions for making your reading experience better. If someone has a magic bullet solution that will help others get the downloaded source code in one piece, please let me know at John@JohnMuellerBooks.com.

 

Creating a CodeBlocks Project with Multiple Existing Files

Most real world C++ projects include multiple source files. Book I Chapter 5 of C++ All-In-One Desk Reference For Dummies shows how to create a project that has multiple source files. The first example, found in \Author\BookI\Chapter05\MultipleSourceFiles, discusses two .CPP files. The second example starts on page 115 and you find it in \Author\BookI\Chapter05\MultipleSourceFiles2. This example includes two .CPP files and a single .H file. I’ll use the files from the second example for this post. The example works the same as the one in the book, but in this case, we’ll start with the three files and create a project around them.

You need to start with a CodeBlocks project. It’s possible to use either an existing project or create a new project to hold the files. In either case, once you have a project to use, you simply add the files you want to it, set the build options for those files, and then create your application. The following steps create a new project, add the files from MultipleSourceFiles2 to it, set the build options, compile the resulting project, and show you the results.

  1. Choose File > New > Project. You’ll see the New From Template dialog box.
  2. Highlight the Empty Project template as shown here:MultipleSourceFiles01
  3. Click Go. You’ll see the Empty Project wizard. If you’re seeing the Welcome screen, click Next to get past it.
  4. Type the name of the project (the example uses MultipleSourceFiles3) in the Project Title field and choose a location for the project (the example uses \Author\BookI\Chapter05) in the Location field. If you’re following the example, your wizard should look like the one shown here:
    MultipleSourceFiles02
  5. Click Next. Look in the Compiler field and ensure that the GNU GCC Compiler option is selected.
  6. Click Finish. The wizard creates a blank project for you.

At this point, you have an empty project without any files in it. However, you can add files to any existing project. The following steps add the files from the MultipleSourceFiles2 project to this project.

  1. Right click the project entry (MultipleSourceFiles3) in the Projects tab of the Management window and choose Add Source Files from the context menu. You see the Add Files to Project dialog box shown here.

MultipleSourceFiles03

  • Locate the \Author\BookI\Chapter05\MultipleSourceFiles2 folder on your system.
  • Click on main.cpp. Ctrl+Click on safestuff.cpp and safestuff.h. You’ll see all three files added to the File Name field.
  • Click Open. You’ll see the Multiple Selection dialog box. This dialog box contains entries for each of the builds that you specified when creating the project. The default is to use the files you’re adding in all of the builds as shown here. (The example uses all of the files in all of the builds.)
    MultipleSourceFiles04
  • Configure the files you’ve selected by choosing the build the file should appear part of and click OK. You’ll see all three files added below the MultipleSourceFiles3 entry in the Projects tab of the Management window as shown here:
    MultipleSourceFiles05

 

This technique adds existing files to a different project. Notice that the files are still referenced in the original project. If you make a change to these files, the changes will also appear in the original project. Of course, that’s not always what you want to do. So, you need an alternative for those situations where you want a copy of the file in a new project. In this case, use Windows Explorer to copy the files from the MultipleSourceFiles2 folder to the MultipleSourceFiles3 folder. You then use Steps 1 through 5, with the MultipleSourceFiles3 folder as the source, to add the files to the project.

Many developers find the need to use existing files in a project. It’s something you’ll do quite often, especially with header files. Of course, when working with header files you also have the option of using the #include directive. Please let me know if you have any questions about this process at John@JohnMuellerBooks.com.

Checking Your Compiler in CodeBlocks

Compilers are important because they turn your human-readable source code into executable code that the computer understands. Selecting the right compiler is essential if you want to obtain the best results from your application. Some readers have asked, “Just how do you select a compiler when working with C++ All-In-One Desk Reference For Dummies?” The book assumes that you’re using the GNU GCC Compiler setting and there isn’t any guarantee another compiler will work with the book’s source code. Use these steps to check your compiler setting.

  1. Open the CodeBlocks application.
  2. Choose Settings | Compiler and Debugger. You’ll see the Compiler and Debugger Settings dialog box shown here:
    CompilerSettings
  3. Choose GNU GCC Compiler in the Selected Compiler field as shown in the figure.
  4. Click OK.

You should be ready to work with the book’s code at this point. Let me know if you have any problems choosing the right compiler at John@JohnMuellerBooks.com.

Handling Source Code in Books

One of the biggest conundrums for the technical writer is how to handle source code in a book. The goal is to present an easily understood example to the readerone that demonstrates a principle in a clear and concise manner. In fact, complexity is a problem with many examplesthe author tries to stuff too much information into the example and ends up obfuscating the very principles that the reader is supposed to obtain. So, very often simplicity must win the day in creating application source code for a book, despite the desire of the author to present something more real world, something with additional glitz and polish.

Because the goal of an example is to teach, very often the examples you see in a book have more comments than those that you see in real life. An example in a book must include as much information as possible if the code is going to fulfill its purpose. Of course, book comments should illustrate all the best principles of creating comments in real code. In short, if real world code looked a bit more like book code, then its possible that developers would spend far less time trying to figure code out and more time making changes.

Some readers will take the author to task because the code may not always provide the error trapping that production code provides. In fact, as with many teaching environments, the safety features in code are often removed for the sake of clarity. This problem plagues other environments too. All of my woodworking magazines post a note near the beginning of the magazine telling the reader that the safety devices have been removed for the sake of clarity and that no one in their right mind would actually work with woodworking equipment without the safety devices. Likewise, the code you see in a book often lacks good error trapping, making the principle that the code demonstrates clearer, at the cost of fragility. You can usually cause book examples to break easily, but no one in their right mind would create production code like that.

The feature that I’ve constantly worked on with the code in my books is accessibility. In as much as possible, the code demonstrates how to make an application usable by those with special needs. Of course, as with the exception handling, it isn’t always possible to add all of the required accessibility features without making the code less clear. Still, I’m a strong advocate of making code completely accessible whenever possible.

Readers will likely question just how useful book code is if it leaves safety and accessibility features out. Remember that the goal is to teach. Let me know your thoughts about source code in books at John@JohnMuellerBooks.com.

 

Using the Book’s Source Code

At least some readers try to hand type the source code found in C++ All-In-One Desk Reference For Dummies. Working with source code when you’re learning a new programming language is hard enough; typing it in by hand and getting a good result is nearly impossible in many cases. I recommend that you always use the code from the book’s CD so that you can avoid potential typos. If you experience problems using the code from the book’s CD, please query me at John@JohnMuellerBooks.com; there may be something that isn’t set up correctly on your system.  The examples on the CD should compile and work, but I always emphasize the word “should”
because each system and setup is slightly different (making things exciting for all of us).

To use the code on the CD, follow these steps:

  1. Copy the Author folder from the CD to your hard drive.
  2. Right click the Author folder and choose Properties from the
    context menu.  You’ll see the Author Properties dialog box.
  3. Clear the Read-only check box. Click OK. You’ll see a Confirm
    Attribute Changes dialog box.
  4. Click OK. Windows will remove the read-only attribute from all
    of the files. You’re ready to begin using the source code supplied with the
    book.

To use a particular example, navigate to that examples folder under the Author folder.  Say you want to work with the AddInteger example in Book I Chapter 2.  You’d navigate to the \Author\BookI\Chapter02\AddInteger.  To open the project, simply double click the associated .CBP file.  In this case, you’d double click the AddInteger.cbp file and CodeBlocks will open with the example loaded and ready for you to work with.