[New-bugs-announce] [issue40341] Programming FAQ includes actively discouraged solutions; Should those be removed?

[Dominik V.]

New submission from Dominik V. <dominik.vilsmeier1123 at gmail.com>:

The Programming FAQ contains multiple solutions (examples) which it describes as "shouldn't be used". The question is why are these included in the first place? Some of them are complicated in a way that a (new) programmer is unlikely to discover them by themselves.

Below I include all the relevant parts, since I wasn't sure whether to open a new issue for each them.

# [How do I write a function with output parameters (call by reference)?](https://docs.python.org/3/faq/programming.html#how-do-i-write-a-function-with-output-parameters-call-by-reference)

Among others it contains these two list items:

> 2. By using global variables. This isn’t thread-safe, and is not recommended.
> [...]
> 5. Or bundle up values in a class instance: [...] There’s almost never a good reason to get this complicated.

Especially number (5) is a pretty obscure way of solving that particular problem (even more so since a perfectly viable solution exists with (1), which is again recommended at the end of the paragraph). This additional recommendation of (1) at the end of the paragraph feels only necessary to draw attention away from the above do-not-use-solutions.

Also solutions (3) and (4) are basically equivalent in a sense that they rely on mutable builtin objects. So either they could be merged in one example or the list version could be left out altogether.

# [How do I use strings to call functions/methods?](https://docs.python.org/3/faq/programming.html#how-do-i-use-strings-to-call-functions-methods)

The last bullet point:

> Use locals() or eval() to resolve the function name: [...] Note: Using eval() is slow and dangerous. If you don’t have absolute control over the contents of the string, someone could pass a string that resulted in an arbitrary function being executed.

This solution proposes to use `eval` and then actively discourages its use later on. Instead it could mention `globals` as an analogy to `locals` with the example of retrieving a globally defined function in another namespace.

# [How can I sort one list by values from another list?](https://docs.python.org/3/faq/programming.html#how-can-i-sort-one-list-by-values-from-another-list)

The second part of the paragraph speaks about using a `for` loop with repeated `append` instead of using the previously mentioned list comprehension. It then speaks about the many reasons why the usage of a `for` loop is discouraged here, so it seems strange that it was mentioned in first place. Also, right now, 50% of the whole section are devoted to an analysis about what not to do for the last step which distracts from the actual solution. IMO it is sufficient to just show the list comprehension.

----------
assignee: docs at python
components: Documentation
messages: 366878
nosy: Dominik V., docs at python
priority: normal
severity: normal
status: open
title: Programming FAQ includes actively discouraged solutions; Should those be removed?
type: enhancement
versions: Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue40341>
_______________________________________