Increasing Boredom Order

When I'm organizing information that don't have a more demanding order, I like to try to put it in order of increasing boredom.

For example, let's take header files (even though languages that make you do things like this are BondageAndDisciplineLanguages. Sigh. That the whole world would use Smalltalk).

 #include <iostream>
 #include "Glayven.h"
 #include "Object.h"
 #include <string>
 #include <map>
 #include <algorithm>
 #include "AfarReachingEvilMacro.h"
 #include "Smayven.h"

If you just slap them in like this, you have to read the whole list to see if there's anything interesting. Let's try that again:

 #include "AfarReachingEvilMacro.h"
 #include "Smayven.h"
 #include "Glayven.h"
 #include <map>
 #include <algorithm>
 #include "Object.h"
 #include <string>
 #include <iostream>

Then, this way, you can keep reading until you get bored (because it's only going to get worse).

This maps naturally to the way people read: meticulously at first, then progressively less meticulous as it becomes less and less rewarding.

IMO, a better ordering for this case would be g.

 #include <algorithm>
 #include <map>
 #include <string>
 #include <iostream>

 #include "AfarReachingEvilMacro.h"
 #include "Smayven.h"
 #include "Glayven.h"
 #include "Object.h"

I think it is important to highlight this example. In cases where you may find a lot of header files included, the case for alphabetical includes is strong. A maintainer does not need to guess where header files are, particularly when it comes time to remove or resolve includes. Besides, ConsistencyIsTheKeyToGoodLiving? (and while IncreasingBoredomOrder is consistent, it is hardly universely consistent).

I think that the first include should always be yourself. Then you immediately know if your header file makes assumptions about the environment where its included.

For example:

Foo.h:

  class Foo : public Bar
  {
    //...
  };

Foo.c:

#include "Bar.h" #include "Foo.h"

If you did this, then you'd miss the bug in the .h file (which should include all its interface-dependencies).

With some compilers, performance issues force you to include the standard header files first, so you can use the PrecompiledHeader? feature.

It should be fairly straight forward to automatically verify that all of your headers compile by themselves, which would be certain to catch that bug as well. Of course, it's also pretty straight forward to automatically test that the right header is first in the file, so you've got options -- DanilSuits

IncreasingBoredomOrder looks like a special case of the PrincipleOfLeastConfusion, i.e., you don't expect the FarReachingEvilMacro buried deep in the code...

...Except it might have to be, given that it presumably contains the FarReachingEvilMacro, which could conceivably changing the meaning of some of the other included headers.

CategoryOrganization