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.
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
A great little cheap book on avoiding, fighting, and automatically
preventing bugs. Every programmer in the world should own a copy of this
great book, and should use it religiously.
If anyone has a book they want to see reviewed, I will be happy to oblige. Just
mail me and tell me which. Publishers can send me books at the address on my
personal page at the end of the magazine, and I will review all OS/2
development-related and advanced user books I receive.
Please note that books aimed at different audiences should only be compared with
great care, if at all. I intend to concentrate on the strong points of the
books I review, but I will point out any weaknesses in a constructive manner.
Summary
Notes
Legend
A+
Ground-breaking, all-around outstanding book
A
Excellent book. I want to see this happen a lot
A-
Excellent book with minor flaws
B+
Very good book with minor flaws or omissions
B
Good book with some flaws and omissions
B-
Good book, but in need of improvement
C+
Mediocre book, some good stuff, but needs an update
C
Mediocre book, some good stuff, but badly needs fixing
C-
Mediocre book, little good stuff, desperately needs fixing
D
Don't buy this book unless it is one of a kind
F
Don't buy this book, period
