Updated STYLE.md for code formatting consistency

[cooper-mj]

The prior style reference re: printing code output seemed inconsistent; especially in cases where multiple functions are within a single code block, it may at times be nonobvious whether the commented output refers to the function above (correct), or below (incorrect). This new code formatting reduces this ambiguity and is more consistent with the expression output syntax.

[parthsarin]

Good points! I agree that situation can be confusing. I have the following concerns, though:

• Your proposal can result in horizontally long code blocks where people have to scroll left and right, which is something I was trying to avoid because printed output can have long horizontal lines where returned output usually doesn't.
• This can be much more disorienting for someone interpreting these notes with a screen reader. See this guide from the APA:

  Furthermore, consecutive spaces may be annoying for people using screen readers or other assistive technologies. Depending upon what settings they use, they may have to listen to “space, space” or endure pauses between sentences that are longer than necessary.

  This is in reference to the fact that subsequent lines would have a bunch of spaces between them.

I'm not sure if it affects your code very much since when you have multiple print expressions it's really clear which one causes which print statement, I believe.

As a counter-proposal, we could drop the extra space and just do:

some_expression
# Some printed output

[cooper-mj]

Great point re: accessibility - I wouldn't have considered the "space, space, space" audio thing. Though I'd suggest that this also renders our current formatting somewhat moot: as an example, the code segment,

expression() # => True

May read out "expression open parentheses close parentheses space hash equals greater than space true," - and I can imagine that the nice implication sign that we've devised (which I find to be a handy visual) then becomes a source of confusion for people using screen readers.

Let's follow up in person in our sync today?

[parthsarin]

Sure! I will briefly drop this resource in here that points out that reading punctuation is really difficult. Some of these decisions are actually design decisions that the screen readers have made. It's often preferable to read out the punctuation in these expressions rather than create confusion by omitting them.

Also, I don't think that you gave the correct readout because the screen reader wouldn't read the spaces (just like it doesn't read spaces between words). Finally, someone could create a macro that reads => as "results in" or something but it's more difficult to create such a macro for the repeated spaces that follow a printed expression that's offset.

Okay, looks like I accidentally gave a more detailed answer. Sorry for getting carried away – this is just something I'm really passionate about!

[cooper-mj]

I didn't know that about screen readers - that was interesting to learn how some punctuation is read and some omitted, thanks for sharing the resource! 😊

I hear what you're saying about the macros, but I don't think we should rely on someone making a macro for the use case of this symbol in our course - just something to keep in mind.

Also, a question - do you know what screen readers do re: indentations in code? Since I can't imagine that a Python expression within an if statement within a for loop would be read as "space space space space space space space space space space space space expression," I suspect there's some functionality built in to manage repeated spaces. The question is whether it would kick in after a hash symbol, or whether it would only kick in if the spaces are leading padding on the line.