Feedback Search Top Backward Forward
EDM/2

The Codesmith's Library

Written by Carsten Whimster

   

Introduction

In The Codesmith's Library, I focus on development books and materials. I write this column from the point of view of an intermediate programmer. Pick up whichever book strikes your fancy, and join the growing group of people following our programming columns.

Please send me your comments and thoughts so that I can make this column what you want it to be. I read and respond to all mail.

Errata

Yet again I am going to trumpet The OS/2 API Project. It is getting quite useful, with more than 36 APIs on site, as well as over 75 #define's. Have a look, and if you have the time, chip in by writing up one or more APIs and sending them to me. I will also happily listen to any and all suggestions regarding layout and format. The more people help out, the quicker this project will become very helpful. The INF version is now out, although it is a touch behind the HTML version. Check it out at [Editor's note: EDM/2 has "absorbed" the OS/2 API Project, although it continues to be a separate entity. It's location has changed, however, and it is reflected in the URL below.]: http://www.iqpac.com/edm2/os2api/index.html

The OS/2 API Project aims at documenting the entire OS/2 API and distributing it as a free document, to help out people who can't afford the IBM documentation, or have something better to spend their money on. I figure it can only help the number of OS/2 programs out there if more people have access to this information.

OS/2 Quick Reference Library, Volume 2, Message Functions

This is the second book in the same series as WIN Functions, OS/2 Quick Reference Library Volume 1, which I previously reviewed. Here are the chapter headings:


1.  How to Use This Book
2.  Notebook Control Messages
3.  Button Control Messages
4.  Combo Box Messages
5.  Container Control Messages
6.  Direct Manipulation Messages
7.  Entry Field Messages
8.  File Dialog Messages
9.  Font Dialog Messages
10. Help Manager Messages
11. List Box Control Messages
12. Multiline Entry Messages
13. Menu Control Messages
14. Profile Messages
15. Scroll Bar Messages
16. Slider Control Messages
17. Static Control Messages
18. Spin Button Messages
19. Title Bar Messages
20. Value Set Control Messages
21. Window Messages
Appendix A: Data Type Structures
Appendix B: Error Code Definitions
Appendix C: Container Notification Codes

As you can see from the picture of this book, it is bound with ring binding. All reference books should be bound this way, or at least with the O'Reilly-style binding, but unfortunately this is rarely the case. `Nuff said.

At the start of each chapter, there is a little section with cross-references to other related messages. Unfortunately, there are no page numbers given, only which chapter they are in.

Each message has a title, a brief description, message declarations (ie. param1, param2, and reply), parameters, returns, remarks and default processing. The remarks section is where you will probably spend most of your reading time, but unfortunately, I find that it is not always complete. Many, if not most, of these messages are sent by a call to some API, but this reference does not discuss these related APIs. In addition, some special properties of certain messages are not discussed either, such as the fact that sending MM_SETDEFAULTITEMID actually converts a cascade menu to a conditional cascade menu. Even though this is a message reference, I find myself wishing for a stronger connection to the related APIs. In general, however, the descriptions are quite good, if occasionally incomplete.

The layout of the chapters is logical, being alphabetical by message name though the whole book. The lack of cross-reference page-numbers is a bother, though. As an example, if you are looking for the LM_SEARCHSTRING message, you will find it on page 186. At the start of the chapter, page 175, there are references to other related messages, such as WM_CONTROL. To find this, you must then flip around until you find it on page 372. The fact that the messages are alphabetical through the whole book helps somewhat, but this is still 3 separate searches though the pages. This could have been minimized by following the same format as the OS/2 Warp API series, with page numbers listed, or even the same as the earlier book in the same series!

Again, this book is not a tutorial by any means, but it does provide a description for every message I have ever come across, which is more than any other book on the market can say.

I recommend this book, but despite the fact that it is competent, it misses the opportunity to go that extra mile and become the great reference book that some of its companion books are. I suspect that it will be surpassed by the next message book on the market, unless it is updated first.

Summary

This little reference book has the only message descriptions out there currently, and it is quite invaluable as such. Nonetheless, there are a number of convenience features missing, such as page number references, see also sections, coloured chapters (on the page ends, a la Sidekick, see volume 4 issue 2), and descriptions of related functions. It is good, but due to the lack of these items, I feel that a newer book could quickly eclipse this one. I rate it a B.

Message Functions, OS/2 Quick Reference Library Volume 2, Scholin

  • Van Nostrand Reinhold, ISBN 0-442-01898-3, $20US, $30CAN.
    Note that Van Nostrand Reinhold has sold its OS/2 library to John Wiley and Sons, and hence this book will now be obtainable through John Wiley, rather than VNR.
  • Intended audience: PM C Programmers
  • Mark: B

A good reference, but misses out on several convenience features. This is the only message reference on the market currently, to my knowledge, so it wins by default.

Writing Solid Code

This book maybe one of the most important books to come out in a long time, especially right now. It focuses on how to avoid writing bugs, how to prevent bugs, and how to fix bugs properly. Here are the chapters:


1. A Hypothetical Compiler
2. Assert Yourself
3. Fortify Your Subsystems
4. Step Through Your Code
5. Candy-Machine Interfaces
6. Risky Business
7. Treacheries of the Trade
8. The Rest is Attitude
Epilogue: Where Do You Go from Here?
Appendix A: Coding Checklists
Appendix B: Memory Logging Routines
Appendix C: Answers

It is interesting that this book should come from Microsoft. There have been many public statements by (sometimes anonymous) officials at Microsoft, saying things like "you only ever have to get 90% of the product working", in addition to the extraordinary bugginess of the initial release of Word 6.0, and on and on. It is interesting to note that Maguire no longer seems to work for Microsoft. I can't offer any explanation for these seeming contradictions, only suggest that this book was ignored by the programmers of Word and Windows 95, and followed strictly by the NT programmers .

The book starts with a short intro, which among other things encourages the use of Hungarian Notation for variable naming. I was able to find these notations on the web fairly easily by searching for "Hungarian AND Notation" on Yahoo and Web Crawler.

Chapter 1 discusses a hypothetical compiler which is able to catch all problems in your code. Maguire goes on to explain that of all the most desirable error messages, many are already implemented in modern compilers, but most people turn off this error detection because they either do not understand the message, or they code in unsafe ways and find the messages annoying. He goes on to recommend the use of lint and other tools, on a religious basis. At the end of this and all the chapters, there is a short section with questions to encourage the reader to think more about the underlying issues of the chapter. There is even a little suggested project for the reader to perform, if he or she is very enthusiastic.

Chapter 2 weighs the pros and cons of the standard C library's assert, and then goes on to define a better one. This is then demonstrated with several code examples. Again, the emphasis here is on the prevention and automatic detection of bugs. Documentation of tricky code is also recommended, again with some real examples. Most of the examples in this book are taken from the real process of developing Excel, mostly on the Mac. Maguire started as a programmer for Excel, and later moved up to be a team lead. The assert routine developed by Maguire is used in a variety of different situations to detect a multitude of hard-to-spot bugs lurking in the wings of the application.

Fortifying your subsystems is the theme of chapter 3. The intent here is that you should provide debug-only double- checks of important algorithms, ensure that all code runs in testing, destroying garbage, initializing memory, and so on. These checks mostly occur at debug-time only, of course, so as to avoid slowing down the gold code.

Stepping through your code with a debugger is the topic of chapter 4. This seemingly time-wasting trick will save lots of time debugging code that never worked quite right in the first place, but it has to be done when the code was written, and the ideas clear in the mind of the programmer, of course, not two years later.

In chapter 5, Maguire makes an interesting comparison between function interfaces and candy-machine interfaces. Writing function interfaces in such a way as to be unambiguous is more important than apparent at first, and even the standard C library is rife with examples of poor interfaces. One example is getchar() which returns, of course, an int! Separating error codes from return values is but one piece of advice you will find in this chapter.

Risk, and proper use of the language is the major topic of chapter 6. It is amazing how many programmers will code a straight-forward task in a quirky, non-portable way, only because it seems more clever or faster, when in fact it is neither. Discover other language tips in chapter 6.

Resisting the temptation of writing clever, but obscure code is one of the focuses of chapter 7. Not referencing memory already freed is yet another tip, which seems all to obvious, but which many programmers do nevertheless. Treat input parameters as read-only, output-parameters as write- only, and so on. Not falling into the trap of thinking that tight C means tight machine code is yet another example. Use the debugger to get a feel for what code the compiler generates here. Finally, a little-realized aspect of development is that novice programmers tend to be the ones who maintain code, so experienced programmers should resist the temptation to write difficult to understand code, in all but the most extreme situations, since this code will not be understood, and thus most likely be ripped out by maintenance programmers.

In the last chapter we are told to get the correct attitude to go along with all our new-found knowledge of bugs. Bugs never just disappear by themselves, for example, yet many programmers use this as an excuse. Do not add extra unnecessary features to products just because they are easy to add either, since this new (easy) code is yet another spot where bugs can hide and bite you from. This last chapter has many other great suggestions.

The real strength of this book is that the tips themselves often sound silly, derogatory, and obvious, but in the context of the examples given, I came to realize again and again that I too had fallen for many of these traps. Read the whole book, page for page, and follow the advice given.

Summary

This book is very important, and every serious developer should take a jet, not run, to the nearest bookstore to pick up a copy. It has an incredible array of methods for avoiding and fighting bugs, and in these bug- ridden, bloated code days, this is more important than ever before in history. Do not assume that you can do the things I mentioned in this review, and be done. They are only representative of what Maguire discusses. This books is so full of tricks and explanations that you just do not want to miss, and this book is really cheap and well worth the money. A+.

Writing Solid Code, Maguire

  • Microsoft Press, ISBN 1-55615-551-4, $US24.95, $32.95CAN, UK21.95.
  • Intended audience: C/C++ Programmers
  • Mark: A+

Reviewed Books

Our Bookstore has reviews and links to Amazon for all books we have reviewed in the past, as well as several books waiting to be reviewed, and others which we recommend.