4 ms·

Indicative of what? Are you trying to say that a the docs should have "Python for X programmers" sections, foreach (no pun intended) X in {Perl, PHP, Haskell,

by junke 10y ago

Indicative of what? Are you trying to say that a the docs should have "Python for X programmers" sections, foreach (no pun intended) X in {Perl, PHP, Haskell, Lisp, Go, Javascript, C++, ...}? That would be nice, but what is even better is a totally different resource that aggregates idioms for all languages: https://www.rosettacode.org/wiki/Loops/Foreach https://www.rosettacode.org/wiki/Loops/Foreach

lawpoop 10y ago
That the first result is a stackoverflow question about the language rather than a documentation page, is indicative that getting started with the language is not so straight-forward, even factoring in documentation. If you're googling 'python foreach', you're probably at the beginner level, and the fact that a documentation page is not the first result means that the beginners documentation is not very discoverable. The fact that there's a not-closed, highly-upvoted, highly-ranked stackexchange question about this very basic issue in existence /at all/ is what one might call a "documentation smell".
- junke 10y ago
  The documentation contains "for-each" and "for each", but sadly not "foreach". Why should "foreach" be in the documentation? There is no "foreach" keyword in Python. If you are looking for "foreach", someone else will look for "python do until", "python fold", "python switch" and maybe another one for "python macros" or "python transducer". Some of those searches are legitimate, because "foreach" is quite used outside of Python and "switch" should be expected to be defined in every language. However, the documentation states what the language is, not what it isn't. The goal of a reference documentation is like a dictionary: you define your words w.r.t. the other words defined in your language; this is already quite a complex task. But you don't mention words from other languages because that would start to be overly confusing and a burden to maintain (now you have to check how other languages evolve). There are other resources to make connections between languages.
  - lawpoop 10y ago
    > Why should "foreach" be in the documentation? To make it easier to find "for", "for each", and "for-each"?
    - junke 10y ago
      How come you know "foreach" in the first place, this is not even a correct english term? You learn it from another language? Wonderful, but why should every keyword from every programming language ever designed be present in the Python docs?
      - lawpoop 10y ago
        I never argued for every for every keyword from every programming language. But like I said, that there's a stackoverflow question about this one, I think, is indicative.
        junke 10y ago
        And this one is special because?

by junke 10y ago

lawpoop 10y ago

That the first result is a stackoverflow question about the language rather than a documentation page, is indicative that getting started with the language is not so straight-forward, even factoring in documentation. If you're googling 'python foreach', you're probably at the beginner level, and the fact that a documentation page is not the first result means that the beginners documentation is not very discoverable. The fact that there's a not-closed, highly-upvoted, highly-ranked stackexchange question about this very basic issue in existence /at all/ is what one might call a "documentation smell".

junke 10y ago
The documentation contains "for-each" and "for each", but sadly not "foreach". Why should "foreach" be in the documentation? There is no "foreach" keyword in Python. If you are looking for "foreach", someone else will look for "python do until", "python fold", "python switch" and maybe another one for "python macros" or "python transducer". Some of those searches are legitimate, because "foreach" is quite used outside of Python and "switch" should be expected to be defined in every language. However, the documentation states what the language is, not what it isn't. The goal of a reference documentation is like a dictionary: you define your words w.r.t. the other words defined in your language; this is already quite a complex task. But you don't mention words from other languages because that would start to be overly confusing and a burden to maintain (now you have to check how other languages evolve). There are other resources to make connections between languages.
- lawpoop 10y ago
  > Why should "foreach" be in the documentation? To make it easier to find "for", "for each", and "for-each"?
  - junke 10y ago
    How come you know "foreach" in the first place, this is not even a correct english term? You learn it from another language? Wonderful, but why should every keyword from every programming language ever designed be present in the Python docs?
    - lawpoop 10y ago
      I never argued for every for every keyword from every programming language. But like I said, that there's a stackoverflow question about this one, I think, is indicative.
      - junke 10y ago
        And this one is special because?