[Docs] CodingStandards: for_each is discouraged

[lebedev.ri]

Summary

As per disscussion in D83351, using for_each is potentially confusing,
at least in regards to inconsistent style (there's less than 100 for_each
usages in LLVM, but ~100.000 for range-based loops

Therefore, it should be avoided.

[hubert.reinterpretcast]

llvm/docs/CodingStandards.rst

1305

Even if what's available in the context of the code is a pair of iterators and a callable (and using a range-based for loop would involve extra boilerplate)?

[lebedev.ri]

llvm/docs/CodingStandards.rst

1305

That is my understanding, yes.

[nickdesaulniers]

As per lengthy/heated disscussion in D83351,

Probably could drop those adjectives. =P Also, s/disscussion/discussion/.

using for_each is potentially confusing,

I guess @dblaikie did use the term confusing, but it might be useful to better reflect his point about confusion in regards to inconsistent style in the commit message. It certainly begs the question otherwise.

llvm/docs/CodingStandards.rst

1305

it might be useful to provide more information here.

Use of X is discouraged because ...

IIUC @dblaikie 's points in https://reviews.llvm.org/D83351#2139727 and https://reviews.llvm.org/D83351#2139861 were that:

1. more concise error messages.
2. more concise unless an existing function/method/lambda already exists.

I love functional programming styles, but if an inline lambda definition isn't shorter than a range-for, I agree with @dblaikie and feel a lambda is overkill.

[lebedev.ri]

It's okay if no new labmbda is needed though.

llvm/docs/CodingStandards.rst

1305

I'm not really sure i understand the point about error message.
Is this better?

[lebedev.ri]

@dblaikie does this look like the wording you'd expect?

[dblaikie]

In D83431#2142420, @lebedev.ri wrote:

@dblaikie does this look like the wording you'd expect?

Yep, looks alright, thanks!

[hubert.reinterpretcast]

llvm/docs/CodingStandards.rst

1306

Typo: s/the the/if the/;

llvm/docs/CodingStandards.rst

 loops wherever possible for all newly added code. For example:
 
 .. code-block:: c++
 
   BasicBlock *BB = ...
   for (Instruction &I : *BB)
     ... use I ...
 
+Usage of ``std::for_each()``/``llvm::for_each()`` functions is discouraged,
+unless the the callable object already exists.
+
 Don't evaluate ``end()`` every time through a loop
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In cases where range-based ``for`` loops can't be used and it is necessary
 to write an explicit iterator-based loop, pay close attention to whether
 ``end()`` is re-evaluated on each loop iteration. One common mistake is to
 write a loop in this style: