fix: text style

Author: cssmagic

content/chapter-4/410.md

@@ -4,7 +4,7 @@ title: "[译] [XXX] XXXXXXXXXXXXXXXX"
 ---
 
 
-## 4.1 **Why we need to read code**
+## 4.1 Why we need to read code
 
 When we talk about reading code, what we mean is being able to understand what code does by looking at it. There are two such levels of understanding.
 
@@ -18,25 +18,28 @@ The second is being able to determine the overall purpose of a program. As profe
 
 At the end of these two chapters, we’ll want you to be able to do both at the level of being able to interpret the code produced by Copilot. We’ll start focusing on that line-by-line understanding but toward the end, you’ll start being able to look at a small chunk of code and determine its purpose.
 
-**Listing 4.1 Best Word function for Scrabble, reprinted from Chapter 3**
-
-def best\_word(word\_list): """
-
-word\_list is a list of words.
-
-Return the word worth the most points. """
-
-best\_word = "" best\_points \= 0
-
-for word in word\_list: points \= num\_points(word) if points > best\_points:
-
-best\_word = word best\_points \= points
-
-return best\_word
-
-We can illustrate the difference between these two levels of reading code by referring back to our best\_word function from Chapter 3, reprinted in listing
-
-4.1 above. A **tracing description** of what this program does would be a description of each line. For example, we would say that we're defining a function called best\_word. We have a variable called best\_word that we start off as a string with no characters, otherwise known as the empty string. (It’s unfortunate that the function and this variable are both called \`best\_word\`, because it makes it trickier to refer to one or the other, but that’s what Copilot gave us.) We also have another variable best\_points that we start at 0. Then we have a for loop over each word in the word\_list. Inside the for loop, we call our num\_points helper function... and so on. (We’ll be explaining how we know what each line of code does over the next two chapters!).
+We can illustrate the difference between these two levels of reading code by referring back to our `best\_word` function from Chapter 3, reprinted in the following listing.
+
+> Listing 4.1 Best Word function for Scrabble, reprinted from Chapter 3
+
+```python
+def best_word(word_list):
+    """
+word_list is a list of words.
+    
+Return the word worth the most points.
+"""
+    best_word = ""
+    best_points = 0
+    for word in word_list:
+        points = num_points(word)
+        if points > best_points:
+            best_word = word
+            best_points = points
+    return best_word
+```
+
+A **tracing description** of what this program does would be a description of each line. For example, we would say that we're defining a function called `best\_word`. We have a variable called `best\_word` that we start off as a string with no characters, otherwise known as the empty string. (It’s unfortunate that the function and this variable are both called `best\_word`, because it makes it trickier to refer to one or the other, but that’s what Copilot gave us.) We also have another variable `best\_points` that we start at 0. Then we have a for loop over each word in the `word\_list`. Inside the for loop, we call our `num\_points` helper function... and so on. (We’ll be explaining how we know what each line of code does over the next two chapters!).
 
 
 
@@ -50,12 +53,6 @@ There are three reasons why we want you to be able to read code.
 
 2. **Informing testing.** Understanding what the code is doing line by line is useful on its own, but it also helps turbocharge your ability to effectively test. For example, in the next chapter, you'll learn about loops; that they can cause your code to repeat zero times, one time, two times, or as many times as needed. You'll be able to combine that knowledge with what you already know about testing to help you identify important categories of cases to test.
 
-3. **Helping you write code.** We know—you want Copilot to write all of your code! We want that, too. But inevitably, there will be code that Copilot just doesn't get right, no matter how much prompt engineering you do. Or maybe enough prompt engineering could finally cajole
-
-  
-
-Copilot to write the correct code, but it would be simpler and faster to just do it ourselves. In writing this book, the two of us strive to have Copilot write as much code as possible. But, because of our knowledge of Python programming, we are often able to see a mistake and just fix it without going through any hoops to have Copilot fix it for us. More
-
-long-term, we want you to be empowered to learn more programming on your own, and having an understanding of Python is our way to bridge you from this book to other resources later. There is research evidence that being able to trace and explain code is prerequisite to being able to write code \[1\].
+3. **Helping you write code.** We know—you want Copilot to write all of your code! We want that, too. But inevitably, there will be code that Copilot just doesn't get right, no matter how much prompt engineering you do. Or maybe enough prompt engineering could finally cajole Copilot to write the correct code, but it would be simpler and faster to just do it ourselves. In writing this book, the two of us strive to have Copilot write as much code as possible. But, because of our knowledge of Python programming, we are often able to see a mistake and just fix it without going through any hoops to have Copilot fix it for us. More long-term, we want you to be empowered to learn more programming on your own, and having an understanding of Python is our way to bridge you from this book to other resources later. There is research evidence that being able to trace and explain code is prerequisite to being able to write code \[1\].
 
 Before we get to it, we need to be clear about the level of depth that we're striving for. We're not going to teach you every nuance of every line of code. Doing so would revert us back to the traditional way that programming was taught prior to tools like Copilot. Rather, through a combination of Copilot tools and our own explanations, we're going to help you understand the gist or overall goal of each line of code. You will need more than this if you endeavor to write large portions of programs in the future. We are trying to target the sweet spot between "this code is magic" and "I know exactly how every line of the code works."

content/chapter-4/420.md

@@ -4,13 +4,13 @@ title: "[译] [XXX] XXXXXXXXXXXXXXXX"
 ---
 
 
-## 4.2 **Asking Copilot to explain code**
+## 4.2 Asking Copilot to explain code
 
 In Chapter 2, when setting up your computer to use GitHub Copilot, you installed the GitHub Copilot Labs extension to Visual Studio Code. This is an experimental extension that is changing rapidly and is designed to offer new features that are not quite ready for everyday use. We're going to show you one of its best features right now: explaining what Python code does!
 
 We suspect that, soon, the Copilot Labs extension, or parts of it, will be folded into the main Copilot extension. If that happens, the specific steps we give here may vary somewhat, and in that case, we encourage you to consult more general GitHub Copilot documentation.
 
-For now, with the Copilot Labs extension installed, you can highlight some code that you want Copilot to describe to you. Let's try this with our best\_word function.
+For now, with the Copilot Labs extension installed, you can highlight some code that you want Copilot to describe to you. Let's try this with our `best\_word` function.
 
 
 
@@ -24,56 +24,49 @@ For now, with the Copilot Labs extension installed, you can highlight some code
 
 First, click on the Copilot Labs tab in your Activity Bar (on the left-hand side of VSCode) and you should see a window similar to figure 4.1.
 
-> Figure 4.2 The code from the best\_word function highlighted in the editor.
-
-![](chapter-4.files/chapter-48299.png)
-
 
 
 Next, highlight all of the code for our best\_word function as is highlighted in figure 4.2. (You may need to have Copilot generate the code for you again if you didn't save it from Chapter 3.)
 
+> Figure 4.2 The code from the `best\_word` function highlighted in the editor.
+
+![](chapter-4.files/chapter-48299.png)
+
+After highlighting the code, you should now see the code appear in the left in the EXPLAIN feature as shown in figure 4.3
+
 > Figure 4.3 The code from the best\_word function appearing in Copilot Labs.
 
 
 
 ![](chapter-4.files/chapter-48572.png) 
 
-After highlighting the code, you should now see the code appear in the left in the EXPLAIN feature as shown in figure 4.3
+  
+
+Figure 4.4 shows the different prompts provided by Copilot that you can use to ask for code explanations. Each will generally yield different responses that vary in how specific they are and whether they produce fewer or more examples. We'll leave it at the default prompt of “Explain Code,” but if you like, you can try other prompts from the drop-down box (shown in figure 4.4). The current options are "Explain Code," "Code Does Following," "Code Does Following (English)," and "Show Example Code." There's also a "Custom" option that allows you to use whatever prompt you like.
 
 > Figure 4.4 The different options for explaining your code in Copilot Labs.
 
 
 
 ![](chapter-4.files/chapter-48774.png) 
 
-  
-
-Figure 4.4 shows the different prompts provided by Copilot that you can use to ask for code explanations. Each will generally yield different responses that vary in how specific they are and whether they produce fewer or more examples. We'll leave it at the default prompt of “Explain Code,” but if you like, you can try other prompts from the drop-down box (shown in figure 4.4). The current options are "Explain Code," "Code Does Following," "Code Does Following (English)," and "Show Example Code." There's also a "Custom" option that allows you to use whatever prompt you like.
-
 The last step is to click Ask Copilot (as shown as the bottom button in figure 4.3). You'll get an explanation of the code. As usual, Copilot is nondeterministic, so your results will likely differ from ours. In fact, if an explanation is confusing you, you might try clicking Ask Copilot again or changing the prompt to get a different explanation. As educators, this is the start of a dream come true, where students will be able to ask for as many explanations as they need to fully understand how code works.
 
-**COPILOT lab explanations can be wrong**
-
-As with the code produced by Copilot, the explanations from Copilot Labs can be wrong too. You might be thinking, “Wait, what’s the value of a tool to understand code if it can be wrong?!” First, let us say that we agree, this can be really frustrating. However, it is right often enough in our experience that it can be really helpful, particularly for understanding code basics like the things we’re teaching in these two chapters. Moreover, what students do now when they are confused about their code is to ask friends or websites about the code and, candidly, those make mistakes too. A way to help mitigate the potential for error is to ask Copilot for its explanation a couple times as you are less likely to get grossly incorrect answers across multiple tries.
+> **Copilot lab explanations can be wrong**
+> 
+> As with the code produced by Copilot, the explanations from Copilot Labs can be wrong too. You might be thinking, “Wait, what’s the value of a tool to understand code if it can be wrong?!” First, let us say that we agree, this can be really frustrating. However, it is right often enough in our experience that it can be really helpful, particularly for understanding code basics like the things we’re teaching in these two chapters. Moreover, what students do now when they are confused about their code is to ask friends or websites about the code and, candidly, those make mistakes too. A way to help mitigate the potential for error is to ask Copilot for its explanation a couple of times as you are less likely to get grossly incorrect answers across multiple tries.
 
 Here's what Copilot gave us the first time we asked:
 
+```python
 """ Here is the explanation for the code above:
-
-1. We define a function called best\_word that takes one argument,
-
-2. We define the variables best\_word and best\_points and set them
-
-3. We use a for loop to iterate over the elements in word\_list.
-
-4. We define a variable called points that is equal to the result
-
-5. We use an if statement to check if points is greater than best
-
-6. If it is, we set best\_word equal to word and best\_points equal
-
-  
-
-7. Finally, we return best\_word. """
+1. We define a function called best_word that takes one argument, word_list. 
+2. We define the variables best_word and best_points and set them equal to the empty string and 0, respectively.
+3. We use a for loop to iterate over the elements in word_list.
+4. We define a variable called points that is equal to the result of calling num_points with word as an argument.
+5. We use an if statement to check if points is greater than best_points.
+6. If it is, we set best_word equal to word and best_points equal to points.
+7. Finally, we return best_word. """
+```
 
 To us, this is an excellent description of what the code does line by line. Notice, however, in order to make full sense of it, you need to know important Python terminology and features. The explanation from Copilot above refers to functions, arguments, variables, strings, for loops, if statements, and returning. You know much of this terminology already, but if you did not, then this explanation would be much less useful. By the end of this and the next chapter, you will know the main terminology and features of Python that you need to interpret a typical explanation from Copilot.