Reducing language complexity
One of the tools to reduce language complexity is "explicitness" or the direct link to help/tutorial/documentation from the concept. The problem with most concepts in computer languages that they don't have distinct markers by which you can recognize one feature or another. For example, you can't recognize that code is generator based or uses metaclass magic without searching for yield or some references to metaclass through the source file. One of the ways to reduce language complexity for new people who read you code, is to prepare them for advanced concepts that your code uses beforehand. For example, with the following section: using generators as yield ^^^ name of this language feature and also help reference ^^^ distinct keywords and feature markers that you enable -- anatoly t.
On Wed, Dec 25, 2013 at 6:47 PM, anatoly techtonik <techtonik@gmail.com> wrote:
Yes, and it's great that you can choose what the keyword is! We should announce the usage of this thus: using using as as using as as using and only then use using and as as as and using. And of course, it's then critical to declare the fact that you're using built-in functions, in case they confuse people too. And their parameters might be confusing, too; best to acknowledge the exact parameter lists that each built-in function uses. Something like this: using print(*values, sep=' ', end='\n', file=sys.stdout, flush=False) using open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None) Of course, this could get rather long, so we could break things out into other files, and put all those 'using' declarations out of the way. Rather than create new syntax for all this, I recommend we use specially-formatted comments; that way, older versions of Python won't be bothered by it. So let's put those two declarations into a file called stdio.h, and put this at the top of your Python script: #include <stdio.h> I'm sure everyone will agree that this is the best thing for Python. ChrisA
On Wed, Dec 25, 2013 at 11:53 AM, Chris Angelico <rosuav@gmail.com> wrote:
Unfortunately, the first message with "Language complexity formula" is deemed to be "not python related" by moderators, so this mail landed without necessary context. Without understanding what adds to the language complexity, this discussion looks useless. -- anatoly t.
On Wed, Dec 25, 2013 at 11:03 AM, anatoly techtonik <techtonik@gmail.com> wrote:
Hi Anatoly, I'm the moderator who rejected your other message titled "Language complexity formula". To be clear, I did not write that the rejected message was "not Python related". I wrote that it was not relevant specifically to the Python-Ideas mailing list. As I'm sure you know, this list is for discussing ideas for the Python language. Your message only suggested a formula for evaluating the complexity of programming languages, while containing no ideas or suggestions for the language itself. If that message was intended as context for this message (titled "Reducing language complexity"), then you should have included the context as well as the suggestion in a single message. To be clear, please do not post several messages which discuss the same subject, or very similar subjects, in parallel. Of course, you are free to add context and explanations to the discussion as you see fit. Regards, - Tal Einat
On Wed, Dec 25, 2013 at 12:03:37PM +0300, anatoly techtonik wrote:
You should write a blog post about the language complexity formula. That way people who are motivated by it can read it, while those who don't won't need to be bothered by an off-topic discussion on something which isn't specific to Python. As for your suggestion to "prepare" readers for "advanced" concepts: using generators as yield who defines what counts as "advanced"? Python for-loops iterating over sequences may seen advanced to a C or Pascal programmer expecting to write code like "for i := 1 to 50 do process(seq[i]);". Exceptions may seem advanced to Java programmers. Even functions may seem terribly advanced to those who have never programmed before. (And I've seen them on the tutor list.) How do you expect this "using" statement to actually help the reader? I have never, ever, not even as a total newbie knowing next to nothing about Python (or any other language) been in a position where I was reading code, came up on a keyword, function or idiom I didn't understand, and thought "Oh, if only this was declared at the beginning of the file, I would have understood it better!". On the other hand, I would feel pretty annoyed if I came across a file containing using flibbit as smudgeon at the start, spent a lot of time reading up on flibbit and smudgeon, then came back to the file and discovered that the hours I had spent was completely unnecessary because the part of the file I cared about didn't actually use flibbit or smudgeon. If a reader comes across "advanced" code they don't understand: def increment(values): for value in values: yield value+1 isn't it pretty trivial for them to ask "what does yield do?". You don't need a "using" statement to lead them to the right search terms. If you think the search terms aren't obvious enough and want to write code aimed at the least-experienced reader, just use a comment, and put it right where it is needed: # Keywords: yield, generator, Python. # http://link-to-your-blog-explaining-this def increment(values): for value in values: yield value+1 -- Steven
When I search for "python generators" instead of "python yield", I get the same docs pages, blog posts, and StackOverflow questions making up 90% of the results, in the same order. When I search for "generators" instead of "yield" at docs.python.org, I get _worse_ results--a bunch of stuff about the C API and then a slew of random modules--the yield statement, the relevant tutorial sections, etc. are nowhere to be seen. When I use the built-in help, "yield" gives me a nice overview; "generators" tells me there's no documentation. So, in what way is "generators" a better term for finding help/tutorial/documentation than "yield"? And I'm not sure what term for the metaclass feature would be better than "metaclass". (If you were going to suggest "using metaclass as __metaclass__" I might agree that was a small improvement, if Python hadn't fixed that 5 years ago.) Sent from a random iPhone On Dec 24, 2013, at 23:47, anatoly techtonik <techtonik@gmail.com> wrote:
On Wed, Dec 25, 2013 at 6:47 PM, anatoly techtonik <techtonik@gmail.com> wrote:
Yes, and it's great that you can choose what the keyword is! We should announce the usage of this thus: using using as as using as as using and only then use using and as as as and using. And of course, it's then critical to declare the fact that you're using built-in functions, in case they confuse people too. And their parameters might be confusing, too; best to acknowledge the exact parameter lists that each built-in function uses. Something like this: using print(*values, sep=' ', end='\n', file=sys.stdout, flush=False) using open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None) Of course, this could get rather long, so we could break things out into other files, and put all those 'using' declarations out of the way. Rather than create new syntax for all this, I recommend we use specially-formatted comments; that way, older versions of Python won't be bothered by it. So let's put those two declarations into a file called stdio.h, and put this at the top of your Python script: #include <stdio.h> I'm sure everyone will agree that this is the best thing for Python. ChrisA
On Wed, Dec 25, 2013 at 11:53 AM, Chris Angelico <rosuav@gmail.com> wrote:
Unfortunately, the first message with "Language complexity formula" is deemed to be "not python related" by moderators, so this mail landed without necessary context. Without understanding what adds to the language complexity, this discussion looks useless. -- anatoly t.
On Wed, Dec 25, 2013 at 11:03 AM, anatoly techtonik <techtonik@gmail.com> wrote:
Hi Anatoly, I'm the moderator who rejected your other message titled "Language complexity formula". To be clear, I did not write that the rejected message was "not Python related". I wrote that it was not relevant specifically to the Python-Ideas mailing list. As I'm sure you know, this list is for discussing ideas for the Python language. Your message only suggested a formula for evaluating the complexity of programming languages, while containing no ideas or suggestions for the language itself. If that message was intended as context for this message (titled "Reducing language complexity"), then you should have included the context as well as the suggestion in a single message. To be clear, please do not post several messages which discuss the same subject, or very similar subjects, in parallel. Of course, you are free to add context and explanations to the discussion as you see fit. Regards, - Tal Einat
On Wed, Dec 25, 2013 at 12:03:37PM +0300, anatoly techtonik wrote:
You should write a blog post about the language complexity formula. That way people who are motivated by it can read it, while those who don't won't need to be bothered by an off-topic discussion on something which isn't specific to Python. As for your suggestion to "prepare" readers for "advanced" concepts: using generators as yield who defines what counts as "advanced"? Python for-loops iterating over sequences may seen advanced to a C or Pascal programmer expecting to write code like "for i := 1 to 50 do process(seq[i]);". Exceptions may seem advanced to Java programmers. Even functions may seem terribly advanced to those who have never programmed before. (And I've seen them on the tutor list.) How do you expect this "using" statement to actually help the reader? I have never, ever, not even as a total newbie knowing next to nothing about Python (or any other language) been in a position where I was reading code, came up on a keyword, function or idiom I didn't understand, and thought "Oh, if only this was declared at the beginning of the file, I would have understood it better!". On the other hand, I would feel pretty annoyed if I came across a file containing using flibbit as smudgeon at the start, spent a lot of time reading up on flibbit and smudgeon, then came back to the file and discovered that the hours I had spent was completely unnecessary because the part of the file I cared about didn't actually use flibbit or smudgeon. If a reader comes across "advanced" code they don't understand: def increment(values): for value in values: yield value+1 isn't it pretty trivial for them to ask "what does yield do?". You don't need a "using" statement to lead them to the right search terms. If you think the search terms aren't obvious enough and want to write code aimed at the least-experienced reader, just use a comment, and put it right where it is needed: # Keywords: yield, generator, Python. # http://link-to-your-blog-explaining-this def increment(values): for value in values: yield value+1 -- Steven
When I search for "python generators" instead of "python yield", I get the same docs pages, blog posts, and StackOverflow questions making up 90% of the results, in the same order. When I search for "generators" instead of "yield" at docs.python.org, I get _worse_ results--a bunch of stuff about the C API and then a slew of random modules--the yield statement, the relevant tutorial sections, etc. are nowhere to be seen. When I use the built-in help, "yield" gives me a nice overview; "generators" tells me there's no documentation. So, in what way is "generators" a better term for finding help/tutorial/documentation than "yield"? And I'm not sure what term for the metaclass feature would be better than "metaclass". (If you were going to suggest "using metaclass as __metaclass__" I might agree that was a small improvement, if Python hadn't fixed that 5 years ago.) Sent from a random iPhone On Dec 24, 2013, at 23:47, anatoly techtonik <techtonik@gmail.com> wrote:
participants (5)
-
anatoly techtonik -
Andrew Barnert -
Chris Angelico -
Steven D'Aprano -
Tal Einat