gh-107432: Rework the style of Doc/howto/functional.rst
#107449
Conversation
…unctional.html This is not a how-to guide; the title has been changed. A future commit should move the document out of /howto This patch removes comments about what the author thinks the reader is familiar with, and the first-person voice that sometimes appeared. Some wording that dated the document has been changed.
|
|
||
| I really like these rules, but you're free to disagree | ||
| about whether this lambda-free style is better. | ||
|
|
||
|
|
||
| Revision History and Acknowledgements |
There was a problem hiding this comment.
Is it necessary to keep this "Revision History and Acknowledgements" section?
There was a problem hiding this comment.
I think the history can be removed, Acknowledgements could be moved to the end (after References) or removed. The references section should also probably have the 'General' subhead removed (I can't add in-line comments there).
AA-Turner
changed the title
Doc/howto/functional.rst
|
|
||
| I really like these rules, but you're free to disagree | ||
| about whether this lambda-free style is better. | ||
|
|
||
|
|
||
| Revision History and Acknowledgements |
There was a problem hiding this comment.
I think the history can be removed, Acknowledgements could be moved to the end (after References) or removed. The references section should also probably have the 'General' subhead removed (I can't add in-line comments there).
AA-Turner
added
needs backport to 3.11
AA-Turner
changed the title
Doc/howto/functional.rstDoc/howto/functional.rst
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
|
(I'll update this from @AlexWaygood You self-requested a review, do you still want to check this or is it okay to merge now? Thanks! |
There was a problem hiding this comment.
Thanks for the PR! I agree that these old articles in the Doc/howto/ directory deserve to be maintained and kept up-to-date. To that end, some of these edits are very useful (we shouldn't assume knowledge of SQL; Python 2.5 is very old).
However, I'm afraid I find most of these edits unnecessary, and several of them pretty harmful. I think I disagree with some of the fundamental premises that lie behind this PR, if I'm honest :/
| Fredrik Lundh once suggested the following set of rules for refactoring uses of | ||
| ``lambda``: | ||
|
|
||
| 1. Write a lambda function. | ||
| 2. Write a comment explaining what the heck that lambda does. | ||
| 3. Study the comment for a while, and think of a name that captures the essence | ||
| of the comment. | ||
| 4. Convert the lambda to a def statement, using that name. | ||
| 5. Remove the comment. | ||
|
|
||
| I really like these rules, but you're free to disagree | ||
| about whether this lambda-free style is better. | ||
|
|
There was a problem hiding this comment.
I don't understand why this section needs to be deleted. It seems to me to be a useful way of thinking about the problem.
It's true that it's written in a slightly more informal style, and a slightly more humorous style, than a lot of the rest of Python's documentation. But Python's Doc/howto/ directory has historically been home to articles that can be written in a freer, more conversational tone than the rest of Python's documentation.
I disagree with retrofitting a new, stricter definition of what it means for a document to be a HOWTO guide onto Python's Doc/howto/ directory, which has historically had a different concept of what how-to guides are and should be.
There was a problem hiding this comment.
A key problem with this page of documentation is that it is not a how-to guide. Whatever else needs to be done with it, it's in the wrong place. If a it does something other than guide the user through a task or problem, it's literally not a how-to guide. Names do matter.
There was a problem hiding this comment.
A key problem with this page of documentation is that it is not a how-to guide.
It is a guide that explains how to apply the functional programming paradigm to Python code
| In this document, we'll take a tour of Python's features suitable for | ||
| implementing programs in a functional style. After an introduction to the | ||
| concepts of functional programming, we'll look at language features such as | ||
| :term:`iterator`\s and :term:`generator`\s and relevant library modules such as | ||
| :mod:`itertools` and :mod:`functools`. |
There was a problem hiding this comment.
Why remove this paragraph? It seems useful for readers to have a summary at the beginning of what the article's going to cover.
There was a problem hiding this comment.
A user's eyes will skip over this. They will just bounce off the new reader, for whom they make little connection. They will not add value for the reader who is returning to the page. The links don't take the reader to the topics in the page, but take them away from it, so they don't serve as useful signposts to what's in the page.
If anyone wants to see what's in the page, they can see that immediately from the page's table of contents, where they will find the topics in the context and order of other topics, and can see their place in the hierarchy of concepts.
In general, summaries of what something is going to discuss (and summaries of what has been discussed) add nothing of value to writing. (A summary of conclusions is a quite different matter.)
There was a problem hiding this comment.
The links don't take the reader to the topics in the page, but take them away from it, so they don't serve as useful signposts to what's in the page.
I think it's useful to mention functools and itertools early-on as concrete examples of standard-library modules that allow you to use the functional programming style in Python, especially since the opening section is so abstract. I wouldn't mind it if you changed the links so that they pointed to the passages later on in this document where it explores the itertools and functools modules.
|
|
||
| val = (yield i) | ||
|
|
||
| I recommend that you **always** put parentheses around a ``yield`` expression | ||
| It's recommended that you **always** put parentheses around a ``yield`` expression |
There was a problem hiding this comment.
The current wording is more concise. It's also more precise -- with your wording, I'm left wondering who exactly is recommending this? Lots of things in this article are just one person's opinion, and never claim to be anything else, but with your rewording here, it makes it sound like it's the official pronouncement from on high about the proper programming style for Python. Removing the usage of the first person throughout the article really muddies the water here about the purpose of this article, in my opinion.
There was a problem hiding this comment.
If they are just one person's opinion, they don't belong in the documentation. The documentation's contract with the user is exactly that: that it is the authoritative pronouncement from on-high about programming in Python. We would never allow the code to be so permissive and lax, to represent merely the way someone feels it's good to do it, and we should hold documentation to the same standards.
There was a problem hiding this comment.
If they are just one person's opinion, they don't belong in the documentation.
Says who? Again, that's not how the CPython project has traditionally thought of HOWTO documents, and it's not what the Doc/howto/ directory in CPython has historically been used for. If you want to substantially rewrite a large portion of the articles in Doc/howto/ based on a new, much stricter idea of what it means for a document to be a HOWTO guide, then I honestly think you should try to achieve a broader consensus among the community before going ahead with something like this. I haven't seen any discussions on Discourse about this, for example.
Personally, I think it's great that we have a space in the CPython documentation for more subjective, personal reflections on programming practices. I'd much prefer we say "it's not a how-to" and move it to some other directory than try to turn the document into something it's not.
There was a problem hiding this comment.
If they are just one person's opinion, they don't belong in the documentation.
Says who? Again, that's not how the CPython project has traditionally thought of HOWTO documents, and it's not what the
Doc/howto/directory in CPython has historically been used for. If you want to substantially rewrite a large portion of the articles inDoc/howto/based on a new, much stricter idea of what it means for a document to be a HOWTO guide, then I honestly think you should try to achieve a broader consensus among the community before going ahead with something like this. I haven't seen any discussions on Discourse about this, for example.
I understood - I believe - that there is consensus on adopting Diátaxis for Python's documentation. There have been discussions, I ran a couple of workshops with the documentation team, and so on.
It's a big project, and it's going to take a long time. My goal is to help set new standards of quality in Python's documentation. It is going to change a lot, and set new expectations. There isn't any other way around this.
Personally, I think it's great that we have a space in the CPython documentation for more subjective, personal reflections on programming practices. I'd much prefer we say "it's not a how-to" and move it to some other directory than try to turn the document into something it's not.
Yes, that is precisely what I described as the goal in the original commit for this pull request. These are steps along the way. But even explanation-type documentation, which is what this particular document is, needs to have authority. Otherwise it is simply not documentation.
There was a problem hiding this comment.
I understood - I believe - that there is consensus on adopting Diátaxis for Python's documentation.
I've liked a lot of what I've seen from the Diataxis work on the CPython docs -- I think it's resulted in some very worthwhile improvements to the docs, and I'm excited to see it continue! We need to consider each change individually, however. There may be broad consensus about using Diataxis as a framework for the CPython docs overall, but I don't really feel like I've seen any kind of consensus-building about what to do with these older HOWTO documents specifically. Endorsement of a general principle/framework is a pretty different thing to endorsing a specific application of that framework that arguably involves redefining the purpose of an entire directory.
I understand that the pace of the change here might be frustrating for you, and I'm sorry for that, but careful review of each change really is necessary, in my opinion.
I ran a couple of workshops with the documentation team
(Super minor nitpick, but there is no "documentation team". There's a docs community -- a group of people who are interested and enthusiastic about improving the CPython docs. But docs contributions come from a wide variety of people, many of whom aren't part of that community, and there are lots of core developers interested in documentation who aren't part of that community. I think it would be a mistake to assume that the people in that community are necessarily representative of the Python community as a whole 🙂)
There was a problem hiding this comment.
Yes, that is precisely what I described as the goal in the original commit for this pull request.
I don't understand -- if the goal is to move this document out of the Doc/howto/ directory, then why do you keep on making arguments based on what a HOWTO is "supposed to be"? If the hope is to reclassify this document altogether, then surely we should do that first, so that we have a clear idea of what the document is meant to be while we're editing it?
| If you need to run cleanup code when a :exc:`GeneratorExit` occurs, it's recommended | ||
| to use a ``try: ... finally:`` suite instead of catching :exc:`GeneratorExit`. |
There was a problem hiding this comment.
I prefer the current wording, which is more concise, and more upfront about the fact that this is one person's opinion.
| Which alternative is preferable? That's a style question; my usual course is to | ||
| avoid using ``lambda``. | ||
| Which alternative is preferable? That's mostly a question of style. |
There was a problem hiding this comment.
This seems to me to be an unnecessary edit
| One reason for my preference is that ``lambda`` is quite limited in the | ||
| You may wish to avoid using ``lambda``, as there are limits to the |
| hard to read. Quick, what's the following code doing? :: | ||
| hard to read. | ||
|
|
||
| Consider:: |
There was a problem hiding this comment.
The use of a rhetorical question aimed at the reader has the effect of shaking up the pace of the prose by suddenly throwing in a different kind of sentence construction. I think it's an enjoyable effect, and don't think it needs to be removed
evildmp
requested review from
1st1,
asvetlov,
gvanrossum and
kumaraditya303
as code owners
AlexWaygood
removed request for
1st1,
asvetlov,
willingc,
gvanrossum and
kumaraditya303
|
Since this was called out as stalled on Discourse, maybe this can be a test case for the newly formed Editorial Board (PEP 732)? |
Sounds like a good idea, though I would like to chime in on Discourse (thanks for opening the thread on Discourse by the way, @evildmp, I appreciate it!). I probably won't be posting my thoughts on Discourse on 25th or 26th December, though :-) |
|
I wonder if maybe a review of this PR by the original author might be useful? He's still around and occasionally contributing (e.g. #107825). @akuchling Would you be willing to give this some of your time? Separately I wonder if perhaps this PR suffers from being too big a chunk to review, especially since it looks like it combines a bunch of small, straightforward improvements and what apparently feels to some as broad, sweeping (and perhaps too broad) changes. (I haven't read the whole PR yet -- I'd like to read the original document first to get a fresh impression.) |
Yes, I'd definitely appreciate that — as I said in #107449 (review), I think a lot of the edits here are straightforward and useful. It would be great to have them separated into their own PR that we could easily merge and backport |
This is not a how-to guide; the title has been changed to the more appropriate "Functional programming in Python". A future commit should move the document out of /howto
This patch removes comments about what the author thinks the reader is familiar with, and the first-person voice that sometimes appeared.
Some wording that dated the document has been changed.
📚 Documentation preview 📚: https://cpython-previews--107449.org.readthedocs.build/