Merge pull request #212 from vplentinax/sync-codeQuality

Sincronización-03-code-quality

Author: vplentinax

1-js/03-code-quality/01-debugging-chrome/article.md

@@ -2,39 +2,39 @@
 
 Before writing more complex code, let's talk about debugging.
 
-All modern browsers and most other environments support "debugging" -- a special UI in developer tools that makes finding and fixing errors much easier.
+[Debugging](https://en.wikipedia.org/wiki/Debugging) is the process of finding and fixing errors within a script. All modern browsers and most other environments support debugging tools -- a special UI in developer tools that makes debugging much easier. It also allows to trace the code step by step to see what exactly is going on.
 
-We'll be using Chrome here, because it's probably the most feature-rich in this aspect.
+We'll be using Chrome here, because it has enough features, most other browsers have a similar process.
 
-## The "sources" pane
+## The "Sources" panel
 
 Your Chrome version may look a little bit different, but it still should be obvious what's there.
 
 - Open the [example page](debugging/index.html) in Chrome.
 - Turn on developer tools with `key:F12` (Mac: `key:Cmd+Opt+I`).
-- Select the `sources` pane.
+- Select the `Sources` panel.
 
 Here's what you should see if you are doing it for the first time:
 
 ![](chrome-open-sources.svg)
 
-The toggler button <span class="devtools" style="background-position:-168px -76px"></span> opens the tab with files.
+The toggler button <span class="devtools" style="background-position:-172px -98px"></span> opens the tab with files.
 
-Let's click it and select `index.html` and then `hello.js` in the tree view. Here's what should show up:
+Let's click it and select `hello.js` in the tree view. Here's what should show up:
 
 ![](chrome-tabs.svg)
 
-Here we can see three zones:
+The Sources panel has 3 parts:
 
-1. The **Resources zone** lists HTML, JavaScript, CSS and other files, including images that are attached to the page. Chrome extensions may appear here too.
-2. The **Source zone** shows the source code.
-3. The **Information and control zone** is for debugging, we'll explore it soon.
+1. The **File Navigator** pane lists HTML, JavaScript, CSS and other files, including images that are attached to the page. Chrome extensions may appear here too.
+2. The **Code Editor** pane shows the source code.
+3. The **JavaScript Debugging** pane is for debugging, we'll explore it soon.
 
-Now you could click the same toggler <span class="devtools" style="background-position:-200px -76px"></span> again to hide the resources list and give the code some space.
+Now you could click the same toggler <span class="devtools" style="background-position:-172px -122px"></span> again to hide the resources list and give the code some space.
 
 ## Console
 
-If we press `Esc`, then a console opens below. We can type commands there and press `key:Enter` to execute.
+If we press `key:Esc`, then a console opens below. We can type commands there and press `key:Enter` to execute.
 
 After a statement is executed, its result is shown below.
 
@@ -56,8 +56,8 @@ A *breakpoint* is a point of code where the debugger will automatically pause th
 
 While the code is paused, we can examine current variables, execute commands in the console etc. In other words, we can debug it.
 
-We can always find a list of breakpoints in the right pane. That's useful when we have many breakpoints in various files. It allows us to:
-- Quickly jump to the breakpoint in the code (by clicking on it in the right pane).
+We can always find a list of breakpoints in the right panel. That's useful when we have many breakpoints in various files. It allows us to:
+- Quickly jump to the breakpoint in the code (by clicking on it in the right panel).
 - Temporarily disable the breakpoint by unchecking it.
 - Remove the breakpoint by right-clicking and selecting Remove.
 - ...And so on.
@@ -70,7 +70,7 @@ That's handy when we need to stop only for a certain variable value or for certa
 
 ## Debugger command
 
-We can also pause the code by using the `debugger` command, like this:
+We can also pause the code by using the `debugger` command in it, like this:
 
 ```js
 function hello(name) {
@@ -89,7 +89,7 @@ That's very convenient when we are in a code editor and don't want to switch to
 
 ## Pause and look around
 
-In our example, `hello()` is called during the page load, so the easiest way to activate the debugger is to reload the page. So let's press `key:F5` (Windows, Linux) or `key:Cmd+R` (Mac).
+In our example, `hello()` is called during the page load, so the easiest way to activate the debugger (after we've set the breakpoints) is to reload the page. So let's press `key:F5` (Windows, Linux) or `key:Cmd+R` (Mac).
 
 As the breakpoint is set, the execution pauses at the 4th line:
 
@@ -105,7 +105,7 @@ Please open the informational dropdowns to the right (labeled with arrows). They
 
     At the current moment the debugger is inside `hello()` call, called by a script in `index.html` (no function there, so it's called "anonymous").
 
-    If you click on a stack item, the debugger jumps to the corresponding code, and all its variables can be examined as well.
+    If you click on a stack item (e.g. "anonymous"), the debugger jumps to the corresponding code, and all its variables can be examined as well.
 3. **`Scope` -- current variables.**
 
     `Local` shows local function variables. You can also see their values highlighted right over the source.
@@ -118,52 +118,65 @@ Please open the informational dropdowns to the right (labeled with arrows). They
 
 Now it's time to *trace* the script.
 
-There are buttons for it at the top of the right pane. Let's engage them.
-
-<span class="devtools" style="background-position:-7px -76px"></span> -- continue the execution, hotkey `key:F8`.
+There are buttons for it at the top of the right panel. Let's engage them.
+<!-- https://github.com/ChromeDevTools/devtools-frontend/blob/master/front_end/Images/src/largeIcons.svg -->
+<span class="devtools" style="background-position:-146px -168px"></span> -- "Resume": continue the execution, hotkey `key:F8`.
 : Resumes the execution. If there are no additional breakpoints, then the execution just continues and the debugger loses control.
 
     Here's what we can see after a click on it:
 
     ![](chrome-sources-debugger-trace-1.svg)
 
-    The execution has resumed, reached another breakpoint inside `say()` and paused there. Take a look at the "Call stack" at the right. It has increased by one more call. We're inside `say()` now.
+    The execution has resumed, reached another breakpoint inside `say()` and paused there. Take a look at the "Call Stack" at the right. It has increased by one more call. We're inside `say()` now.
+
+<span class="devtools" style="background-position:-200px -190px"></span> -- "Step": run the next command, hotkey `key:F9`.
+: Run the next statement. If we click it now, `alert` will be shown.
+
+    Clicking this again and again will step through all script statements one by one.
+
+<span class="devtools" style="background-position:-62px -192px"></span> -- "Step over": run the next command, but *don't go into a function*, hotkey `key:F10`.
+: Similar to the previous the "Step" command, but behaves differently if the next statement is a function call. That is: not a built-in, like `alert`, but a function of our own.
+
+    The "Step" command goes into it and pauses the execution at its first line, while "Step over" executes the nested function call invisibly, skipping the function internals.
+
+    The execution is then paused immediately after that function.
+
+    That's good if we're not interested to see what happens inside the function call.
 
-<span class="devtools" style="background-position:-137px -76px"></span> -- make a step (run the next command), but *don't go into the function*, hotkey `key:F10`.
-: If we click it now, `alert` will be shown. The important thing is that `alert` can be any function, the execution "steps over it", skipping the function internals.
+<span class="devtools" style="background-position:-4px -194px"></span> -- "Step into", hotkey `key:F11`.
+: That's similar to "Step", but behaves differently in case of asynchronous function calls. If you're only starting to learn JavaScript, then you can ignore the difference, as we don't have asynchronous calls yet.
 
-<span class="devtools" style="background-position:-72px -76px"></span> -- make a step, hotkey `key:F11`.
-: The same as the previous one, but "steps into" nested functions. Clicking this will step through all script actions one by one.
+    For the future, just note that "Step" command ignores async actions, such as `setTimeout` (scheduled function call), that execute later. The "Step into" goes into their code, waiting for them if necessary. See [DevTools manual](https://developers.google.com/web/updates/2018/01/devtools#async) for more details.
 
-<span class="devtools" style="background-position:-104px -76px"></span> -- continue the execution till the end of the current function, hotkey `key:Shift+F11`.
-: The execution would stop at the very last line of the current function. That's handy when we accidentally entered a nested call using <span class="devtools" style="background-position:-72px -76px"></span>, but it does not interest us, and we want to continue to its end as soon as possible.
+<span class="devtools" style="background-position:-32px -194px"></span> -- "Step out": continue the execution till the end of the current function, hotkey `key:Shift+F11`.
+: Continue the execution and stop it at the very last line of the current function. That's handy when we accidentally entered a nested call using <span class="devtools" style="background-position:-200px -190px"></span>, but it does not interest us, and we want to continue to its end as soon as possible.
 
-<span class="devtools" style="background-position:-7px -28px"></span> -- enable/disable all breakpoints.
+<span class="devtools" style="background-position:-61px -74px"></span> -- enable/disable all breakpoints.
 : That button does not move the execution. Just a mass on/off for breakpoints.
 
-<span class="devtools" style="background-position:-264px -4px"></span> -- enable/disable automatic pause in case of an error.
+<span class="devtools" style="background-position:-90px -146px"></span> -- enable/disable automatic pause in case of an error.
 : When enabled, and the developer tools is open, a script error automatically pauses the execution. Then we can analyze variables to see what went wrong. So if our script dies with an error, we can open debugger, enable this option and reload the page to see where it dies and what's the context at that moment.
 
 ```smart header="Continue to here"
 Right click on a line of code opens the context menu with a great option called "Continue to here".
 
-That's handy when we want to move multiple steps forward, but we're too lazy to set a breakpoint.
+That's handy when we want to move multiple steps forward to the line, but we're too lazy to set a breakpoint.
 ```
 
 ## Logging
 
-To output something to console, there's `console.log` function.
+To output something to console from our code, there's `console.log` function.
 
 For instance, this outputs values from `0` to `4` to console:
 
 ```js run
 // open console to see
 for (let i = 0; i < 5; i++) {
-  console.log("value", i);
+  console.log("value,", i);
 }
 ```
 
-Regular users don't see that output, it is in the console. To see it, either open the Console tab of developer tools or press `key:Esc` while in another tab: that opens the console at the bottom.
+Regular users don't see that output, it is in the console. To see it, either open the Console panel of developer tools or press `key:Esc` while in another panel: that opens the console at the bottom.
 
 If we have enough logging in our code, then we can see what's going on from the records, without the debugger.
 
@@ -172,12 +185,12 @@ If we have enough logging in our code, then we can see what's going on from the
 As we can see, there are three main ways to pause a script:
 1. A breakpoint.
 2. The `debugger` statements.
-3. An error (if dev tools are open and the button <span class="devtools" style="background-position:-264px -4px"></span> is "on").
+3. An error (if dev tools are open and the button <span class="devtools" style="background-position:-90px -146px"></span> is "on").
 
-Then we can examine variables and step on to see where the execution goes wrong.
+When paused, we can debug - examine variables and trace the code to see where the execution goes wrong.
 
 There are many more options in developer tools than covered here. The full manual is at <https://developers.google.com/web/tools/chrome-devtools>.
 
 The information from this chapter is enough to begin debugging, but later, especially if you do a lot of browser stuff, please go there and look through more advanced capabilities of developer tools.
 
-Oh, and also you can click at various places of dev tools and just see what's showing up. That's probably the fastest route to learn dev tools. Don't forget about the right click as well!
+Oh, and also you can click at various places of dev tools and just see what's showing up. That's probably the fastest route to learn dev tools. Don't forget about the right click and context menus!

1-js/03-code-quality/01-debugging-chrome/chrome-open-sources.svg

@@ -1,8 +1,8 @@
 <style>
 span.devtools {
   display: inline-block;
-  background-image: url(/article/debugging-chrome/toolbarButtonGlyphs.svg);
-  height:16px;
-  width:16px;
+  background-image: url(/article/debugging-chrome/largeIcons.svg);
+  height:18px;
+  width:18px;
 }
 </style>