4 ms·

Sure, in a perfect world i would read the complete tutorial before i get started on a new language. But it's not a perfect world, i want to get stuff done. I h

by huskyr 10y ago

Sure, in a perfect world i would read the complete tutorial before i get started on a new language. But it's not a perfect world, i want to get stuff done. I have twenty years of programming experience, i don't need to learn what a for loop is (the first link) and i don't want to read a whole document just to find a reference to the items() function (second link). I just want to know what the equivalent of foreach() is in Python. Sure, a document with a 'very concise and precise' technical description might be useful to some, just for looking up things it's not. The current alternative is Googling StackOverflow posts.

junke 10y ago
Sure, in a perfect world the documentation would guess who I am and adapt accordingly, be both highly detailed when I need it or informal when I don't. But it's not a perfect world, I want to get stuff done. I have twenty years of programming experience, I know how to find the information I need. Sure, the whole language explained in one place for all kind of people from beginners to experts would be nice. But I have Internet. I type "foreach python" in Google and I see a StackOverflow post.
- lawpoop 10y ago
  > I type "foreach python" in Google and I see a StackOverflow post. That's kind of indicative right there.
  - 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?
falcolas 10y ago
With all due respect, if you have 20 years of programming experience and can't grok BNF, it might be worth stopping attempting to learn new languages and learn BNF instead. Given than BNF defines how Python (and many other languages) is parsed, it's well worth learning.
jacobolus 10y ago
Actually, the folks with 20 years of experience in other languages are the ones who most need to read the Python tutorial. The python code I read from PHP/Java/C++/... “career experts” tends to be worse than the python code I read from people who have only been programming for 2–3 years, because they never bother to learn Python idioms or style, but just keep on writing code in the same old style in every language. It’s certainly possible to dive into a new programming language and start writing nominally working code right away, filling in with a google search whenever you get stuck.. That’s not a way to ever end up with any kind of basic competence in the language though. It also doesn’t give you much of a leg to stand on for complaining. The Python tutorial is short and breezy, a fast read which will put you well on your way to understanding the language. I’d recommend it for anyone who plans to spend more than a day or two reading or writing Python code.

by huskyr 10y ago

junke 10y ago

Sure, in a perfect world the documentation would guess who I am and adapt accordingly, be both highly detailed when I need it or informal when I don't. But it's not a perfect world, I want to get stuff done. I have twenty years of programming experience, I know how to find the information I need. Sure, the whole language explained in one place for all kind of people from beginners to experts would be nice. But I have Internet. I type "foreach python" in Google and I see a StackOverflow post.

lawpoop 10y ago
> I type "foreach python" in Google and I see a StackOverflow post. That's kind of indicative right there.
- 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?

falcolas 10y ago

With all due respect, if you have 20 years of programming experience and can't grok BNF, it might be worth stopping attempting to learn new languages and learn BNF instead. Given than BNF defines how Python (and many other languages) is parsed, it's well worth learning.

jacobolus 10y ago

Actually, the folks with 20 years of experience in other languages are the ones who most need to read the Python tutorial. The python code I read from PHP/Java/C++/... “career experts” tends to be worse than the python code I read from people who have only been programming for 2–3 years, because they never bother to learn Python idioms or style, but just keep on writing code in the same old style in every language. It’s certainly possible to dive into a new programming language and start writing nominally working code right away, filling in with a google search whenever you get stuck.. That’s not a way to ever end up with any kind of basic competence in the language though. It also doesn’t give you much of a leg to stand on for complaining. The Python tutorial is short and breezy, a fast read which will put you well on your way to understanding the language. I’d recommend it for anyone who plans to spend more than a day or two reading or writing Python code.