[mlpack-svn] [MLPACK] #155: order of includes and include protections

[MLPACK Trac]

#155: order of includes and include protections
----------------------+-----------------------------------------------------
 Reporter:  nslagle   |        Owner:                                     
     Type:  wishlist  |       Status:  new                                
 Priority:  major     |    Milestone:                                     
Component:  MLPACK    |     Keywords:  includes, templates, style, nitpick
 Blocking:            |   Blocked By:                                     
----------------------+-----------------------------------------------------
 A little nitpicky, but I prefer includes appearing in a file to appear in
 four blocks:

 {{{
 #include <iostream>  // BLOCK I: standard includes available on virtually
 all
 #include <fstream>   //   systems requiring no additional libraries
 #include <stdlib.h>

 #include <armadillo> // BLOCK II: includes from our installed dependencies
 #include <boost/booster_seat/seatbelt.hpp>
 #include <libxml/parser.h>

 #include <mlpack/core/core.hpp> // BLOCK III: our local library includes
 #include <mlpack/core/tree/spacetree.hpp>

 #include "my_local_class_definition.hpp" // BLOCK IV: my locally required
 headers
 }}}

 In each separate block, alphabetize the listing by header name.  Also,
 headers appearing in block IV should appear using quotes to indicate a
 ''lesser'' status, if you will.  Of course, this ''lesser'' status within
 this file might be (and hopefully is) a higher status in other more
 distant source files.

 By our templating convention, we create the intermediary
 ''do_stuff_ever_impl.hpp'' file to house complicated template methods for
 the class ''DoStuffEver''.  We typically include this implementation
 intermediary at the conclusion of the top header file for the class.

 {{{
 #ifndef DO_STUFF_EVER_HPP
 #define DO_STUFF_EVER_HPP

 class DoStuffEver
 {
 ...
 };

 #include "do_stuff_ever_impl.hpp"
 #endif
 }}}

 This type of include falls under ''BLOCK IV'', so use ordinary double
 quotes rather than angled brackets.

 Finally, in the file ''do_stuff_ever_impl.hpp'', do not use any
 ''#includes''; simply begin the file with

 {{{
 #ifndef DO_STUFF_EVER_HPP
 #error "Do not include this file directly."
 #endif

 #ifndef DO_STUFF_EVER_IMPL_HPP
 #define DO_STUFF_EVER_IMPL_HPP
 ...
 #endif
 }}}

 Restricting this file to contain no additional includes further protects
 us from including the file improperly; any ''includes'' required for this
 file can appear in ''do_stuff_ever.hpp'' above.

-- 
Ticket URL: <http://trac.research.cc.gatech.edu/fastlab/ticket/155>
MLPACK <www.fast-lab.org>
MLPACK is an intuitive, fast, and scalable C++ machine learning library developed by the FASTLAB at Georgia Tech under Dr. Alex Gray.