Re: [boost] Why do many examples lack #includes and namespaces?

Subject: Re: [boost] Why do many examples lack #includes and namespaces?
From: Krzysztof Czainski (1czajnik_at_[hidden])
Date: 2013-12-14 13:15:52

2013/12/13 TyRoXx <tyroxxxx_at_[hidden]>

> The first example for Lambda 1.55 is:
>
> list<int> v(10);
> for_each(v.begin(), v.end(), _1 = 1);
>
> This is not useful at all.
> The first two question that every new user would ask are:
>
> - which header files do I have to include?
> - which namespaces are the things from? Is _1 the global that I already
> know from bind or not?
>
> +1, but I fraze it differently: it would be helpful (not only for
beginners) to put the _minimum_ set of #includes in each snippet, and
supply namespace information. I find aliasing long namespaces at the
beginning of every shown snippet a good idea.

Many libraries' docs have a statement like: "throughout the docs you shoud
assume #include <boost/thislib.hpp> and using namespace boost::thislib;". I
think this is bad practice in examples, because it's bad practice in
general, and examples should also show good style of using the library.

> A useful example would be:
>
> #include <list>
> #include <algorithm>
> #include <boost/lambda/core.hpp>
>
// I'm glad this isn't #include <boost/lambda.hpp>

> int main() {
>
  namespace ll = boost::lambda;

>   std::list<int> v(10);

   std::for_each(v.begin(), v.end(), ll::_1 = 1);

> }
>

I mean, it doesn't hurt that much to put the minimum needed #includes and
namespace aliases in every snippet. This will not only help beginners, but
anyone who wants to copy-paste-modify an example. Could this be made a
guidline for Boost docs in general?

Regards,
Kris