Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Lesson 1 - add info about variable names #663

Open
HeatherAn opened this issue Jul 18, 2019 · 8 comments
Open

Lesson 1 - add info about variable names #663

HeatherAn opened this issue Jul 18, 2019 · 8 comments

Comments

@HeatherAn
Copy link
Contributor

@HeatherAn HeatherAn commented Jul 18, 2019

In Lesson 1 - Analyzing Patient Data, section 'Variables', I would suggest adding that operators (e.g., '+' and '-'), and signs like '!' or '?' cannot be used in variable names.

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Jul 18, 2019

Hi @HeatherAn and congratulations on creating your first ever issue! Could you please elaborate more on why you think this is necessary because our first episode says:

In Python, variable names:

  • can include letters, digits, and underscores
  • cannot start with a digit
  • are case sensitive.

and it seems to cover things like '!' and '?' by not listing them in the first bullet point. We can strengthen the first point by adding 'only'.

@HeatherAn
Copy link
Contributor Author

@HeatherAn HeatherAn commented Jul 18, 2019

Thank you! And yes, I agree that adding 'only' would be enough. Because as it is now, it technically does not exclude anything else. And after those three items there are only 2 examples (the 'weight0' versus '0weight', and the 'weight' versus 'Weight'). Perhaps it would be good to show what happens if someone tries to name a variable with a '-' versus what happens when someone tries to name a variable with a '_'. Then there is one example of each one of the items explained above (although, yes, adding 'only' is already self explanatory).

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Jul 18, 2019

Thank you!

Because as it is now, it technically does not exclude anything else.

You're correct, it does not explicitly exclude anything else nor it says other things are allowed.
In fact, here we're exploiting one of the rules for teaching: "Never hesitate to sacrifice truth for clarity" (see http://third-bit.com/10rules/). When I was writing this paragraph, I decided to sacrifice completeness rather than truth (as it seemed to be the lesser of two evils) and didn't add 'only' because weird characters are, actually, allowed (see below) and while some of them are "letters" in some languages, I'm not sure about all of them:

à = 2
æ = 'wat?'
Æ = 'no way!'
ž = ï == 'ßtrng'= ž * à ++ "..." + æ
print(ᜢ, Æ)

I'm not opposed to adding 'only' but in this case we might be indeed sacrificing truth. In other words, we have to decide what to sacrifice: completeness or truth. Seems like a good talking point, @swcarpentry/python-novice-inflammation-maintainers

Perhaps it would be good to show what happens if someone tries to name a variable with a '-' versus what happens when someone tries to name a variable with a '_'.

I'm guessing that you're proposing an exercise in which learners would try to create two variables one of which would fail. I am not sure it would be a good exercise so early in the lesson because if we add such an exercise (e.g., a- = 1), we would encounter an error and instructors would have to say something like: don't pay attention to the actual error message. It would distract learners and increase the cognitive load.

@emmatalis
Copy link

@emmatalis emmatalis commented Dec 31, 2019

Note: this comment is made in part to satisfy the Carpentries Checkout Procedure Part 1.

I think @HeatherAn was right to start a discussion about this issue, but I don't feel this concern warrants any changes to the lesson. Since the section in question comes so early in the first lesson, I don't think we should add any unnecessarily confusing exercises or language in describing what variable names are legal. I agree that the least confusing way to address @HeatherAn's initial concern is to add "only" to the first bullet point, but I would argue that this sacrifice of truth for completeness is not supported.

I don't think that students find the first bullet point confusing currently, and even though it doesn't explicitly state that things like '!' and '?' are not allowed, it does imply it. If this implication is unclear to any students, and they wish to test a variable name like a- on their own, they would quickly see that this throws an error. To @maxim-belkin's point that some weird characters are allowed, I think any mention of this fact would be unnecessary and potentially confusing.

Aside from leaving this portion of the lesson as it currently stands, I think a good solution may be to add a sentence after the three bullet points discussed above that reads something like: "It is common practice to limit the characters in variable names to letters, digits, and underscores."

@noatgnu
Copy link
Contributor

@noatgnu noatgnu commented Jan 30, 2020

I think it is possible to add a link to the official Python naming convention documentation from PEP 8 for students who would like to explore more about the intricacy of do and don't in good variable naming practices like ASCII compatibility, avoiding use of upper case O, lower case l (el), and upper case I (eye).

@leriomaggio
Copy link
Contributor

@leriomaggio leriomaggio commented Jul 13, 2021

I do also believe that including a reference in the end to Python PEP8 would be definitely beneficial.
IMHO this can help novice programmers, as well as learners with existing experience with other languages to better understand Python language ethos and common practice. The type of things that would make their code more pythonic.

Besides, there exist tools (e.g. flake8) that are also commonly used to enforce the adherence to Python coding style, especially useful when contributing to an open source code base.
I do understand this is far from being novice-level concept but still, in the spirit of catching the attention of the Competent Practitioner, this may also be an extra possible link to add as external reference ? :)

Just saying :)

@ldko
Copy link
Contributor

@ldko ldko commented Jul 16, 2021

Regarding @leriomaggio's comment mentioning teaching toward making code more pythonic, that is something I think we need to be careful not to spend much time on. While Python was chosen as the language to teach the lesson in for reasons such as it would be easier to learn than some other languages and because it is used across many disciplines, the goal of the material is not to make workshop attendees Python programmers. It is more to teach people how to use programming to make their work more repeatable and to automate workflows. We try not to focus too much on specifically how things are done in Python, but to teach concepts that can be applicable if you end up working in another language.

That said, one possibility for a sentence to link those who are interested in further information while hopefully not being too distracting to novices:

While there is a little more to the rules and recommendations of naming variables in Python, if you stick to the above guidelines, you will do fine.

Though, I'm curious what @maxim-belkin would say to such an addition.

@maxim-belkin
Copy link
Contributor

@maxim-belkin maxim-belkin commented Jul 19, 2021

While there is a little more to the rules and recommendations of naming variables in Python, if you stick to the above guidelines, you will do fine.

Though, I'm curious what @maxim-belkin would say to such an addition.

I like the sentence -- it's clear and succinct. I wonder, though, whether it will increase the (cognitive) load of this section, because it introduces things (concepts) not covered in the lesson.

My other thoughts:

  • +1 👍🏻   for explaining that +, -, ?, !, *, ^, # can't be used in variables names. Perhaps, this could be added as an additional bullet point ("Can't use these symbols in variable names: ...") -- An exercise with a "gotcha" is # = 1 doesn't error out -- why?
  • +0.5 👍🏻   for explaining that there are several words that we can't use for variable names (reserved Python keywords). I'm only +0.5 here because we don't know any Python keywords at this point.
  • Not sure that pointing to (or even mentioning) pep8 at this point is a good idea (this is Python specific and is a layer of additional recommendations rather than hard rules).
  • The language used in the "lexical_analysis" page might be difficult to understand. If you agree, we could, instead, do the second bullet point above... and maybe add an exercise "Which of the following are good names for variables?" But, again, the problem is that we don't know any keywords at this point. Though, we could show help("keywords")...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants