Touch ups and edits for clarity in instructions, introductions, hints and stub file. (exercism#3791)

Author: BethanyG

concepts/basics/introduction.md

@@ -2,18 +2,26 @@
 
 Python is a [dynamic and strongly typed][dynamic typing in python] programming language.
 It employs both [duck typing][duck typing] and [gradual typing][gradual typing], via [type hints][type hints].
+Python puts a strong emphasis on code readability and (_similar to Haskell_) uses [significant indentation][significant indentation] to denote function, method, and class definitions.
+
+Python was created by Guido van Rossum and first released in 1991.
 
 Imperative, declarative (e.g., functional), and object-oriented programming _styles_ are all supported, but internally **[everything in Python is an object][everythings an object]**.
 
-Python puts a strong emphasis on code readability and (_similar to Haskell_) uses [significant indentation][significant indentation] to denote function, method, and class definitions.
+We'll dig more into what all of that means as we continue through the Python track concepts.
 
-Python was created by Guido van Rossum and first released in 1991.
+This first concept (`basics`)  introduces 4 major Python language features:
+1.  Name Assignment (_variables and constants_),
+2.  Functions (_the `def` keyword and the `return` keyword_),
+3.  Comments, and
+4.  Docstrings.
 
+<br>
 
 ## Name Assignment (Variables & Constants)
 
 Programmers can bind [_names_][facts-and-myths-about-python-names] (also called _variables_) to any type of object using the assignment `=` operator: `<name> = <value>`.
-A name can be reassigned (or re-bound) to different values (different object types) over its lifetime.
+A name can be reassigned (or re-bound) to different values (different object types) over its lifetime:
 
 
 ```python
@@ -37,9 +45,10 @@ A name can be reassigned (or re-bound) to different values (different object typ
 
 ### Constants
 
-Constants are names meant to be assigned only once in a program.
-They should be defined at a [module][module] (file) level, and are typically visible to all functions and classes in the program.
-Using `SCREAMING_SNAKE_CASE` signals that the name should not be re-assigned, or its value mutated.
+Constants are names meant to be assigned only once in a program — although Python will not prevent re-assignment.
+Using `SCREAMING_SNAKE_CASE` signals to anyone reading the code that the name should **not** be re-assigned, or its value mutated.
+Constants should be defined at a [module][module] (file) level, and are typically visible to all functions and classes in a program.
+
 
 
 ## Functions
@@ -92,7 +101,9 @@ def add_two_numbers(number_one, number_two):
 11
 ```
 
+
 Functions that do not have an _explicit_ `return` expression will _implicitly_ return the [`None`][none] object.
+This means that if you do not use `return` in a function, Python will return the `None` object for you.
 The details of `None` will be covered in a later exercise.
 For the purposes of this exercise and explanation, `None` is a placeholder that represents nothing, or null:
 

exercises/concept/guidos-gorgeous-lasagna/.docs/hints.md

@@ -10,7 +10,9 @@
 
 ## 1. Define expected bake time in minutes
 
-- You need to [name][naming] a constant, and [assign][assignment] it an [integer][numbers] value.
+- You need to [name][naming] a [constant][constants], and [assign][assignment] it an [integer][numbers] value.
+  This constant should be the first thing after the docstring that is at the top of the file.
+  Remember to remove the #TODO comment after defining the constant.
 
 ## 2. Calculate remaining bake time in minutes
 
@@ -38,6 +40,7 @@
 
 [assignment]: https://docs.python.org/3/reference/simple_stmts.html#grammar-token-assignment-stmt
 [comments]: https://realpython.com/python-comments-guide/
+[constants]: https://stackoverflow.com/a/2682752
 [defining functions]: https://docs.python.org/3/tutorial/controlflow.html#defining-functions
 [docstrings]: https://docs.python.org/3/tutorial/controlflow.html#tut-docstrings
 [naming]: https://realpython.com/python-variables/

exercises/concept/guidos-gorgeous-lasagna/.docs/instructions.md

@@ -4,52 +4,70 @@ You're going to write some code to help you cook a gorgeous lasagna from your fa
 
 You have five tasks, all related to cooking your recipe.
 
-## 1. Define expected bake time in minutes
+<br>
 
-Define an `EXPECTED_BAKE_TIME` constant that returns how many minutes the lasagna should bake in the oven.
+~~~~exercism/note
+We have started the first function definition for you in the stub file, but you will need to write the remaining function definitions yourself.
+You will also need to define any constants yourself.
+Read the #TODO comment lines in the stub file carefully.
+Once you are done with a task, remove the TODO comment.
+~~~~
+
+<br>
+
+## 1. Define expected bake time in minutes as a constant
+
+Define the `EXPECTED_BAKE_TIME` [constant][constants] that represents how many minutes the lasagna should bake in the oven.
 According to your cookbook, the Lasagna should be in the oven for 40 minutes:
 
 ```python
->>> import lasagna
->>> lasagna.EXPECTED_BAKE_TIME
+>>> print(EXPECTED_BAKE_TIME)
 40
 ```
 
 ## 2. Calculate remaining bake time in minutes
 
-Implement the `bake_time_remaining()` function that takes the actual minutes the lasagna has been in the oven as an argument and returns how many minutes the lasagna still needs to bake based on the `EXPECTED_BAKE_TIME`.
+Complete the `bake_time_remaining()` function that takes the actual minutes the lasagna has been in the oven as an argument and returns how many minutes the lasagna still needs to bake based on the `EXPECTED_BAKE_TIME` constant.
 
 ```python
->>> from lasagna import bake_time_remaining
 >>> bake_time_remaining(30)
 10
 ```
 
+
 ## 3. Calculate preparation time in minutes
 
-Implement the `preparation_time_in_minutes(number_of_layers)` function that takes the number of layers you want to add to the lasagna as an argument and returns how many minutes you would spend making them.
+Define the `preparation_time_in_minutes()` [function][functions] that takes the `number_of_layers` you want to add to the lasagna as an argument and returns how many minutes you would spend making them.
 Assume each layer takes 2 minutes to prepare.
 
 ```python
->>> from lasagna import preparation_time_in_minutes
+>>> def preparation_time_in_minutes(number_of_layers):
+        ...
+        ...
+        
 >>> preparation_time_in_minutes(2)
 4
 ```
 
+
 ## 4. Calculate total elapsed cooking time (prep + bake) in minutes
 
-Implement the `elapsed_time_in_minutes(number_of_layers, elapsed_bake_time)` function that has two parameters: `number_of_layers` (_the number of layers added to the lasagna_) and `elapsed_bake_time` (_the number of minutes the lasagna has been baking in the oven_).
-This function should return the total number of minutes you've been cooking, or the sum of your preparation time and the time the lasagna has already spent baking in the oven.
+Define the `elapsed_time_in_minutes()` function that takes two parameters as arguments: `number_of_layers` (_the number of layers added to the lasagna_) and `elapsed_bake_time` (_the number of minutes the lasagna has been baking in the oven_).
+This function should return the total number of minutes you have been cooking, or the sum of your preparation time and the time the lasagna has already spent baking in the oven.
 
 ```python
->>> from lasagna import elapsed_time_in_minutes
+>>> def elapsed_time_in_minutes(number_of_layers, elapsed_bake_time):
+        ...
+        ...
+        
 >>> elapsed_time_in_minutes(3, 20)
 26
 ```
 
+
 ## 5. Update the recipe with notes
 
-Go back through the recipe, adding "notes" in the form of function docstrings.
+Go back through the recipe, adding "notes" in the form of [function docstrings][function-docstrings].
 
 ```python
 def elapsed_time_in_minutes(number_of_layers, elapsed_bake_time):
@@ -64,3 +82,7 @@ def elapsed_time_in_minutes(number_of_layers, elapsed_bake_time):
     lasagna.
     """
 ```
+
+[constants]: https://stackoverflow.com/a/2682752
+[functions]: https://docs.python.org/3/tutorial/controlflow.html#defining-functions
+[function-docstrings]: https://docs.python.org/3/tutorial/controlflow.html#documentation-strings

exercises/concept/guidos-gorgeous-lasagna/.docs/introduction.md

@@ -14,6 +14,7 @@ This first exercise introduces 4 major Python language features:
 3.  Comments, and
 4.  Docstrings.
 
+<br>
 
 ~~~~exercism/note
 
@@ -25,6 +26,7 @@ On the Python track, [variables][variables] are always written in [`snake_case`]
 [snake case]: https://en.wikipedia.org/wiki/Snake_case
 ~~~~
 
+<br>
 
 ## Name Assignment (Variables & Constants)
 
@@ -33,21 +35,21 @@ A name can be reassigned (or re-bound) to different values (different object typ
 
 
 ```python
->>> my_first_variable = 1  # my_first_variable bound to an integer object of value one.
->>> my_first_variable = 2  # my_first_variable re-assigned to integer value 2.
+>>> my_first_variable = 1  #<-- my_first_variable bound to an integer object of value one.
+>>> my_first_variable = 2  #<-- my_first_variable re-assigned to integer value 2.
 
 >>> print(type(my_first_variable))
 <class 'int'>
 
 >>> print(my_first_variable)
 2
 
->>> my_first_variable = "Now, I'm a string." # You may re-bind a name to a different object type and value.
+>>> my_first_variable = "Now, I'm a string." #<-- You may re-bind a name to a different object type and value.
 >>> print(type(my_first_variable))
 <class 'str'>
 
 >>> print(my_first_variable)
-"Now, I'm a string."  # Strings can be declared using single or double quote marks.
+"Now, I'm a string."  #<-- Strings can be declared using single or double quote marks.
 ```
 
 
@@ -90,10 +92,11 @@ IndentationError: unindent does not match any outer indentation level
 
 Functions _explicitly_ return a value or object via the [`return`][return] keyword:
 
+
 ```python
 # Function definition on first line, explicit return used on final line.
-def add_two_numbers(number_one, number_two):
-  return number_one + number_two   
+>>> def add_two_numbers(number_one, number_two):
+        return number_one + number_two   
 
 
 # Calling the function in the Python terminal returns the sum of the numbers.
@@ -109,6 +112,7 @@ def add_two_numbers(number_one, number_two):
 
 
 Functions that do not have an _explicit_ `return` expression will _implicitly_ return the [`None`][none] object.
+This means that if you do not use `return` in a function, Python will return the `None` object for you.
 The details of `None` will be covered in a later exercise.
 For the purposes of this exercise and explanation, `None` is a placeholder that represents nothing, or null:
 

exercises/concept/guidos-gorgeous-lasagna/lasagna.py

@@ -8,7 +8,7 @@
 """
 
 
-#TODO: define the 'EXPECTED_BAKE_TIME' constant.
+#TODO: define the 'EXPECTED_BAKE_TIME' constant below.
 
 
 #TODO: Remove 'pass' and complete the 'bake_time_remaining()' function below.
@@ -27,9 +27,15 @@ def bake_time_remaining():
 
 
 #TODO: Define the 'preparation_time_in_minutes()' function below.
-# You might also consider using 'PREPARATION_TIME' here, if you have it defined.
+# You might also consider defining a 'PREPARATION_TIME' constant.
+# You can do that on the line below the 'EXPECTED_BAKE_TIME' constant.
+# This will make it easier to do calculations.
 
 
 
 #TODO: define the 'elapsed_time_in_minutes()' function below.
-# Remember to add a docstring (you can copy and then alter the one from bake_time_remaining.)
+
+
+
+# TODO: Remember to go back and add docstrings to all your functions
+#  (you can copy and then alter the one from bake_time_remaining.)