Headers. This finely tuned instrument – this Stradivarius of programming – this final frontier against the total apocalypse of Java – is starting to fall apart.
Let us face it. No one reads the manual first, but dorks – and those of us who occasionally gets in doubt. That does not mean a manual is not a good idea. It just means, that the manual should not be at the top of the package, or glued to our foreheads. You should not be forced to read the manual on the program selector, each time you want to change the channel on your TV, or read the manual on how to operate Safari, each time you want to read the news. That would quickly get pretty annoying.
None the less, this is that what is happening to one of the most powerful tools of C programming. The headers.
A good header is invaluable, and alone for that reason, I will always despise Java. A good header tells you at a glance what a class contains, and what it can do. Naming conventions. Order of appearance, and even subtle things like spacing or spacers, will guide the reader through the class, and present him with – the essence of it all – right there at his fingertips.
Unfortunately somebody got the idea, that if we inserted the documentation into the header file, he could write a small script, and the documentation would be “for free”. What a load of … Not only are you without any kind of formatting when writing the documentation, you also ruin your header, and will have to spend countless hours, trying to figure out, why the auto generated piece of cr.. does in no way look like what you had pictured in your head. The idea ranks amongst the worst ideas in human history. It is that bad.
So do humanity a favor, and start writing the documentation as it is supposed to be. In a separate file.