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

Subject: Re: [boost] Why do many examples lack #includes and namespaces?
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2013-12-14 15:04:29

On Sat, Dec 14, 2013 at 10:15 PM, Krzysztof Czainski <1czajnik_at_[hidden]> wrote:
> 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?

I don't think that spelling out all includes and namespaces in
examples is a good idea in general. These things clutter the code and
draw attention away from the code that is intended to illustrate
something. That said it is also important that examples are actual and
can be compiled. QuickBook offers a way to achieve this - by importing
the compilable examples into the documentation. The version displayed
in the docs can be as concise as needed and also contain a link to the
compilable version. If anything has to be a guideline, it's this
approach, IMHO.