[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                               |   Resolution:     
  Keywords:  includes, templates, style, nitpick  |     Blocking:     
Blocked By:                                       |  
--------------------------------------------------+-------------------------

Comment (by nslagle):

 My suggestion to add the additional check isn't really intended to
 caricature users; when I approached this library early in the summer, I'd
 never seen ''stuff_impl.h'' files in addition to ''stuff.hpp.''
 Additional code, however frustrating adding four lines to code might be,
 is well-worth it in encouraging proper usage.

 Another solution adopted by others in the C++ template camp is to use a
 different extension for the ''stuff_impl.hpp'' file, perhaps
 ''stuff.impl'' (I can't remember the suffix exactly.)

 @JC: Is our solution to simply provide one gigantic include for the entire
 library, including all of the methods?  I see that armadillo does
 something similar with its global include, though I'm not sure about doing
 this in production code, at least not internally.

 ''An advantage in reducing your include dependencies to the minimum
 necessary to accomplish the task is to ease understanding of the
 dependencies.''

 Namespaces ostensibly help us with this, but we often mitigate this with
 ''using namespace ohWell;''.  Admittedly, we haven't the time right now to
 discover exactly which armadillo dependencies we're using (though likely
 we aren't using very many of them), but we don't necessarily have to
 follow the same sloppy paradigm, at least not internally.

 Take KDE for instance; I don't really need everything available in core.h,
 so probably I can just add three to five internal includes, and anyone
 looking at the code immediately understands the dependencies.  Thus, the
 curious reader can look at the KDE header to see that ''spacetree.hpp,
 hrectbound.hpp, range.hpp,'' and ''log.hpp'' are necessary to make it
 work.

 Externally, for the babes in the woods, we can provide the all-inclusive-
 every-header-on-the-system approach, though that still seems like overkill
 to me.

 The rule we followed in developing simulator C code is to blob together
 includes only when they form a chain of dependencies necessary to make the
 final target run (much like our ''do_stuff.hpp'' and ''do_stuff_impl.hpp''
 dependencies.)

-- 
Ticket URL: <http://trac.research.cc.gatech.edu/fastlab/ticket/155#comment:8>
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.