From a symptom to an actual bug... and more!

I just fixed a bug in one of the modules powering this web site.

It started with a very simple symptom. When creating a new issue in the bug tracker, I got the following PHP E_ALL notice:
Undefined property: stdClass::$cid

Unfortunately, fixing the bug was not a simple matter of suppressing the warning. At first, I couldn't even reliably reproduce the symptom. I had to investigate more in depth and understand the exact circumstances that lead to the faulty manifestation. I finally found the proper way to fix that particular bug.

However, applying the proper fix to the code was not even enough. I was faced with two issues that often plague a developer. First, the code was not totally clear on what it was doing (partly because of the use of "magic numbers", a known anti-feature). Secondly, there was a distinct lack of documentation in the upstream API and of the module's own functionality.

Thus, I started with a single symptom, the aforementioned E_ALL warning.

But I ended fixing three different things: the actual bug, the code obfuscation, and the lack of documentation.

Now, an important concept to keep in mind is that the very same symptom might later lead to a different bug! This occurs very frequently in software development.

Even as a user, not as a developer, when facing a faulty behaviour, our first reflex is to search the net for a given symptom, often an error message. And I have seen many forum threads and issues in bug trackers where discussion get muddied by the fact that some participants talk about the same symptom but that are caused by different bugs.

Thus I want to drive this web site to a point where we can easily make a distinction between a bug and a symptom. To some extent, I have already stated, especially when documenting symptoms I encountered while debugging bash scripts.

Also, I just created the following wiki page where we can document best practices on this topic:

• symptoms vs bugs.