diff --git a/episodes/04-code-readability.md b/episodes/04-code-readability.md index 066770689..831d197f2 100644 --- a/episodes/04-code-readability.md +++ b/episodes/04-code-readability.md @@ -161,7 +161,9 @@ to read and prone to misspellings. `ReadSpeed` (or `read_speed`) would suffice. go with the short version and use an inline comment to describe it further (more on those in the next section). This guidance does not necessarily apply if your variable is a well-known constant in your domain - for example, *c* represents the speed of light in physics. -- Try to be descriptive where possible and avoid meaningless or funny names like `foo`, `bar`, `var`, `thing`, etc. +- Avoid overloading a variable (e.g. *f* could be Fahrenheit or for function or for file or something else) +- Try to be descriptive where possible and avoid meaningless or funny names like `foo`, `bar`, `var`, `thing`, etc. If possible, aim for "self-documenting" code, where the names are meaningful enough that you don't need comments to describe them. +- Avoid using references to cultural knowledge or popular culture or uncommon terms as this can confuse individuals who are not familiar with those references. There are also some restrictions to consider when naming variables in Python: