[docs] FOO and BAR

[Chris Jerdonek]

> Date: Tue, 11 Dec 2012 11:32:27 +0000
> From: <Andrew.Roe at rbs.com>
> Do you think it would be possible to write your documentation avoiding the silly usage of FOO and BAR everywhere?

Sure, it's possible.  However, we're volunteers, and it may take a
fair bit of time: there is a lot of documentation along with many
competing things to do, and it's not necessarily trivial to come up
with real-world examples that are also simple, effective, neutral, and
illustrative.  I think as a group we're aware of this issue.  For
example, the following issue is in the tracker (which includes your
example):

http://bugs.python.org/issue11176


> This is a very very old and boring joke, and does nothing to clarify what you are trying to clarify. If you could include real-world examples in your documentation, rather than "clever" programmer "jokes", learners such as myself would have far more respect for the good work you are obviously doing here.

I wouldn't say that it's a joke or an attempt to be funny or silly.
Names like "foo" and "bar" are simply widely-used neutral placeholder
names, in the same way that "lorem ipsum..." is used as sample text in
many illustrations or that "John Doe" is used as a sample name.  Read
here, for example, for more information:

http://en.wikipedia.org/wiki/Foobar

It's just a convenience for the writer (albeit at the expense of being
"real-world").


> For example, the section on argparser is full of this sort of rubbish:
> argparse.ArgumentParser(description='A foo that bars')
>
> Under what circumstances would you ever put that in a program? Are you mad?

No, we're certainly not.  Also note that it helps to be kind when
writing to people -- especially to volunteers.

--Chris



> Please take this into consideration.
>
> Andrew Roe
> RAD Developer
> Markets & International Banking
> RBS
> 250 Bishopsgate, London, EC2M 4AA, GB
> Office: +44 20 7678 0425
>
>
> ***********************************************************************************
> The Royal Bank of Scotland plc. Registered in Scotland No 90312.
> Registered Office: 36 St Andrew Square, Edinburgh EH2 2YB.
> Authorised and regulated by the Financial Services Authority. The
> Royal Bank of Scotland N.V. is authorised and regulated by the
> De Nederlandsche Bank and has its seat at Amsterdam, the
> Netherlands, and is registered in the Commercial Register under
> number 33002587. Registered Office: Gustav Mahlerlaan 350,
> Amsterdam, The Netherlands. The Royal Bank of Scotland N.V. and
> The Royal Bank of Scotland plc are authorised to act as agent for each
> other in certain jurisdictions.
>
> This e-mail message is confidential and for use by the addressee only.
> If the message is received by anyone other than the addressee, please
> return the message to the sender by replying to it and then delete the
> message from your computer. Internet e-mails are not necessarily
> secure. The Royal Bank of Scotland plc and The Royal Bank of Scotland
> N.V. including its affiliates ("RBS group") does not accept responsibility
> for changes made to this message after it was sent. For the protection
> of RBS group and its clients and customers, and in compliance with
> regulatory requirements, the contents of both incoming and outgoing
> e-mail communications, which could include proprietary information and
> Non-Public Personal Information, may be read by authorised persons
> within RBS group other than the intended recipient(s).
>
> Whilst all reasonable care has been taken to avoid the transmission of
> viruses, it is the responsibility of the recipient to ensure that the onward
> transmission, opening or use of this message and any attachments will
> not adversely affect its systems or data. No responsibility is accepted
> by the RBS group in this regard and the recipient should carry out such
> virus and other checks as it considers appropriate.
>
> Visit our website at www.rbs.com
>
> ***********************************************************************************
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://mail.python.org/pipermail/docs/attachments/20121211/c8f63e0d/attachment.html>
>
> ------------------------------