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

Subject: Re: [boost] Why do many examples lack #includes and namespaces?
From: Mostafa (mostafa_working_away_at_[hidden])
Date: 2013-12-14 16:23:24

On Sat, 14 Dec 2013 12:04:29 -0800, Andrey Semashev  
<andrey.semashev_at_[hidden]> wrote:

> 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.

+1

Whichever way, as long as the information is easily located.