swcarpentry / python-novice-inflammation

Programming with Python
http://swcarpentry.github.io/python-novice-inflammation/
Other
302 stars 780 forks source link

Consistency in use of single- and double-quote marks #854

Open troub1 opened 4 years ago

troub1 commented 4 years ago

In the first episode, "Python Fundamentals," it's mentioned that

And to create a string, we add single or double quotes around some text

and I often take a second there to say that the main thing is to be consistent with which one you choose. And then the workshop proceeds and we're using single-quotes the whole time. Except later, in "Storing Multiple Values in Lists", we start switching to double-quotes about 2/3 through:

binomial_name = "Drosophila melanogaster"
... 

for the rest of the episode, and then back and forth a bit in subsequent episodes, like in "Errors and Exceptions":

def some_function()  
    msg = "hello, world!"  
    print(msg)  
    return msg

and

letters = ['a', 'b', 'c']  
print("Letter #1 is", letters[0])

The latter one seems to follow the style of literals being double-quoted and lists/dicts/etc being single-quoted, but it's different from all previous instances I can see.

It's a small thing, especially since in the very beginning we do say that either can be used, but I would say it increases cognitive load (or simply distraction) on both the learners as well as less experienced instructors because the sudden change is noticed by the learners if the instructor types it as written, and otherwise the instructor has to substitute on the fly when live-coding the example or displaying the exercise. I think it often prompts a question "Why are we doing double-quotes here? Is it significant?" to which I don't really have a good answer except that the lessons are made up from contributions of a large community, and you yourself should try to be consistent 😄

So I'd be thrilled to get this fixed, or to fix it. I assume the SWC style, if there is one, is to single-quote everything since that's how the vast majority of the lesson is written? I'm happy to do a pull request and fix these up, if it should be done.

Thanks! Steven

ldko commented 4 years ago

Hi Steven, Yes, we should be consistent with single vs. double quotes, and in the lesson, where we are inconsistent is not intentional. Like you suggest, it likely came from several people contributing small chunks of episodes over a long period of time. I think it makes sense to consistently use single quotes, and it would be great if you want to do pull requests to fix this issue. I suggest one pull request per episode, for easier review by maintainers. The only place I think we should be using double quotes is for triple double quotes,such as in a docstring, or in the case where the string contains a single quote (not sure this comes up in the lesson). Thank you very much for bringing up the issue and offering to fix it! --Lauren

troub1 commented 4 years ago

Great, I'll get started, and thanks for anticipating my follow-up question(s)!