Re: fix for bug #47381, how to order #includes

[Carnë Draug]

On 25 March 2016 at 23:33, Rik <address@hidden> wrote:
> On 03/25/2016 03:30 PM, Mike Miller wrote:
>> Rik, all,
>>
>> The fix [1] for bug #47381 [2] accidentally breaks building Octave
>> without gl2ps [3]. The header file associated with gl2ps-print.cc,
>> gl2ps-print.h, needs to be #included outside of the HAVE_GL2PS_H
>> condition.
>>
>> This is easy to restore, but any ideas how to avoid accidentally
>> rearranging things like this in the future? I'd be tempted to clean up
>> includes in the same way and make the same mistake. The graphics classes
>> are particularly complicated. Should we comment when #includes are
>> grouped for particular reasons like this? Should we use additional #if
>> blocks to separate conditional includes from unconditional includes, and
>> conditional code from unconditional code?
>>
>> [1]: http://hg.savannah.gnu.org/hgweb/octave/rev/ab8760b1245d
>> [2]: https://savannah.gnu.org/bugs/?47381
>> [3]: https://hydra.nixos.org/build/33552213
>>
> Apparently "no good deed goes unpunished".  I was adding a header include
> and thought I'd take the extra minute to clean up and rationalize the other
> includes--only to introduce a bug.
>
> I suppose comments are the first defense.  Another possibility is to
> actually spend time to go through the list of #includes for the various C++
> files and rationalize them: remove the unnecessary ones, re-order them into
> alphabetical order if no better plan exists, etc.  If that were done then I
> could trust that the grouping that kept gl2ps-print.h outside the #ifdef
> block was made for a reason.  As it is, I usually assume that there is no
> rhyme or reason as to why the includes are there.
>

Last year I ran iwyu (Includ What You Use)[1] on Octave code which found a
missing includes (and some no longer includes as well).  I ended up not
acting on it for lack of time but if anyone is looking at it now.

About the order of includes, I have been using the following order (with an
empty line betweeb each of the sections):

  1. This file header (not included if it's a header itself).
  2. C system files.
  3. C++ system files.
  4. Other libraries' .h files.
  5. Rest of project .h files.

which I took from the Google C++ Style guide [2]

I have noticed that we've had several discussions about coding style
recently.  It may be worth to write such style guide.  I like how Google's
Python [3] and C++ [4] style guides are written, listing cons and pros of
the style (and alternatives), and explanation the final decision.

Carnë

[1] https://github.com/include-what-you-use/include-what-you-use
[2] 
https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes
[3] https://google.github.io/styleguide/pyguide.html
[4] https://google.github.io/styleguide/cppguide.html