classification
Title: Programming FAQ includes actively discouraged solutions; Should those be removed?
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Dominik V., ZackerySpytz, docs@python, miss-islington, rhettinger
Priority: normal Keywords: patch

Created on 2020-04-20 20:59 by Dominik V., last changed 2020-10-16 20:29 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 22726 merged ZackerySpytz, 2020-10-16 18:08
PR 22727 merged miss-islington, 2020-10-16 18:44
Messages (5)
msg366878 - (view) Author: Dominik Vilsmeier (Dominik V.) * Date: 2020-04-20 20:59
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.
msg366881 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-04-20 21:10
I rather like the discussion in [How do I write a function with output parameters].  Some variant of each of those solutions arise in code reviews over and over again.  Rarely do the occur in simplistic examples, but they do occur.  The simple examples given are the easiest way to learn about the anti-patterns.

In the section [How do I use strings to call functions/methods?], let's eliminate the eval() variant which isn't really helpful.  The locals() technique does occur in practice and is worth showing.

In the section [How can I sort one list by values from another list], I concur that we can completely eliminate "alternative" and its explanatory text.
msg378734 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-10-16 18:44
New changeset a22a19f3548f6064035e7c59a19cda1e9506db92 by Zackery Spytz in branch 'master':
bpo-40341: Remove some "discouraged solutions" in Doc/faq/programming.rst (GH-22726)
https://github.com/python/cpython/commit/a22a19f3548f6064035e7c59a19cda1e9506db92
msg378744 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-10-16 20:28
New changeset 0fbddb14dc03f61738af01af88e7d8aa8df07336 by Miss Skeleton (bot) in branch '3.9':
bpo-40341: Remove some "discouraged solutions" in Doc/faq/programming.rst (GH-22726) (GH-22727)
https://github.com/python/cpython/commit/0fbddb14dc03f61738af01af88e7d8aa8df07336
msg378745 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-10-16 20:29
Dominik, thanks for the suggestion.

Zackery, thanks for the PR.
History
Date User Action Args
2020-10-16 20:29:09rhettingersetstatus: open -> closed
resolution: fixed
messages: + msg378745

stage: patch review -> resolved
2020-10-16 20:28:07rhettingersetmessages: + msg378744
2020-10-16 18:54:04rhettingersetversions: + Python 3.10, - Python 3.8
2020-10-16 18:44:38miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request21693
2020-10-16 18:44:25rhettingersetmessages: + msg378734
2020-10-16 18:08:14ZackerySpytzsetkeywords: + patch
nosy: + ZackerySpytz

pull_requests: + pull_request21692
stage: patch review
2020-04-20 21:10:57rhettingersetnosy: + rhettinger
messages: + msg366881
2020-04-20 20:59:25Dominik V.create