Bug free Windows API coding!

While following a discussion on a programming forum today I came across ,once again, one of the common problems when writing pure Windows API code.

What is that, you may ask ?

The Windows API is quite complex and it has a lot of rules. It takes time to become experienced with the API, so many programmers likely browse the web (or their favorite forums) for examples of code which does what they want. Now here is the common error:

Programmers may simply take the code they find and just copy it “as is” into their applications code (or port it to their programming language as closely to the original as possible).

The first rule of writing software one should follow is:

Never use code you find on the internet (or in books) “as is” ! It doesn’t matter if the code is open source or freeware or public domain. Just because you can (legally or morally) use it, does not mean you should use it.

One should always view such code only as an “example” to learn from and not code to be used. Even if the code is found in Windows documentation, don’t use it “as is”. You should simply use such code to learn the “concept” at hand, then examine each of the API’s used and then read the API docs to fully understand those API’s. Then write the code from scratch yourself making sure you fully debug it.

Why is this so important ?

Let me give you a real world example. When I first was learning how to use DIB (Device Independent Bitmaps) sections in Windows, the code I came across in my research had some serious errors in it. I first went to my favorite programming forum and found some working code, but did not realize it had errors in it. The code worked, but it did call some incorrect API’s which was not good. I then browsed the internet and found code (in C) which was not the same programming language that I use and it uses similar code to what I first had found. Since I never use other peoples code, no matter how trustworthy it may appear, I began to start digging into the API’s used. My first find was that the code was treating the return handle (bitmap) of the CreateDIBSection API function as if it were a Global memory handle and the code was calling Global memory API’s to lock the bitmap memory handle. It seemed to make sense at first, but as I started to read the API docs, I never found any mention of Global Memory with DIBsections. The API docs, while at times quite terse, are at least pretty consistant in warning you of any additional API’s required to use a particular feature. To make a long story short, the code I found on the web was wrong. The amazing thing was, all that C code which was in error, found its way into other programming languages code (on the forums I frequent). Some very experienced API programmers were also using that code, which was many years old by now. The point is that the errors in code, were being perpetutated over the years again and again and even in multiple programming languages.

Where this gets interesting is a strange problem some don’t consider. Some errors when writing API code, may be better tolerated by earlier versions of Windows (ie. 95/98,ME/XP).  This means the code with some errors may actually work on some older versions of Windows. The error may not effect the task at hand (meaning the code appears to do what it is suppose to do), but many errors can cause the operating system to become unstable (or the dreaded GPF). Since older versions of Windows may tolerate the errors, programmers don’t realize the code has a problem until it is run on the next version of Windows. A programmer may say “its worked perfectly on Windows XP, but there is something wrong in Windows 7 which causes it to crash the application”. The programmer assumes the problem is with Windows 7, not realizing that the problem is with their code. They simply didn’t realize the code was in error because Windows XP tolerated the error, while Windows 7 like was more picky about the error and it responded more quickly to it ((ie. crashed the app).

The worse part about this is that such programming errors are often perpetuated year after year by “bad code” on the internet or even in books.

So learn the lesson to never use others code “as is”. Always fully understand the code so you can write it from scratch yourself and read the API docs carefully to make sure the code is written correctly. Then you will have code which will be more reliable and likely will work flawlessly on the next version of Windows.