diff --git a/1-js/03-code-quality/01-debugging-chrome/article.md b/1-js/03-code-quality/01-debugging-chrome/article.md index fb793f218..c2647370e 100644 --- a/1-js/03-code-quality/01-debugging-chrome/article.md +++ b/1-js/03-code-quality/01-debugging-chrome/article.md @@ -1,71 +1,71 @@ # Depuração de erros no navegador -Antes de escrevermos código mais complexo, vamos falar de debugging (depuração de erros). +Antes de escrevermos código mais complexo, precisamos de falar de debugging (depuração de erros). -[Depuração](https://pt.wikipedia.org/wiki/Depura%C3%A7%C3%A3o) é o processo de procura e correção de erros num programa. Todos os navegadores (*browsers*) modernos e muitas outras plataformas (*environments*) suportam ferramentas de *debugging* -- uma UI (Interface de Utilizador) especial disponível nas ferramentas do desenvolvedor (*developer tools*) que torna a depuração de erros muito mais fácil. Ela também permite rastrear o código passo-a-passo para ver exatamente o que está a ser executado. +[Depuração](https://pt.wikipedia.org/wiki/Depura%C3%A7%C3%A3o) é o processo de procura e correção de erros em um dado programa. Todos os navegadores (*browsers*) modernos e muitas outras plataformas (*environments*) suportam ferramentas de (*debugging*) -- uma UI (Interface de Usuário) especial que está disponível nas ferramentas do desenvolvedor (*developer tools*) tornando assim, a depuração de erros muito mais fácil. Ela também permite rastrear o código passo-a-passo para entender exatamente o que está sendo executado. -Aqui, vamos utilizar o Chrome porque tem muitas funcionalidades, mas a maioria dos outros navegadores possui um processo similar. +Aqui, vamos utilizar o navegador Google Chrome dadas as suas muitas funcionalidades, porém, a maioria dos navegadores atuais possui recursos similares. -## O painel "*Sources*" +## O painel *Sources* -A versão do seu Chrome pode parecer um pouco diferente, mas ainda assim deverá ser óbvio o que lá encontre. +Devido à versão do seu Chrome, partes da interface podem parecer diferentes mas ainda assim deverá ser possível entender o que lá encontrar. - Abra a [página exemplo](debugging/index.html) no Chrome. - Ative as ferramentas do desenvolvedor com `key:F12` (Mac: `key:Cmd+Opt+I`). - Selecione o painel `Sources`. -Aqui está o que poderá ver, se o estiver a fazer pela primeira vez: +Aqui está o que poderá ser visto caso esteja a fazê-lo pela primeira vez: ![](chrome-open-sources.svg) -O botão de alternador abre o separador com os ficheiros. +O botão de alternar abre o separador com os arquivos. -Vamos clicar nele, e selecionar `hello.js` na vista de árvore de recursos apresentada. Aqui está o que deveria ser mostrado: +Vamos clicar nele e selecionar `hello.js` na representação da árvore de recursos aberta. Abaixo está o que você poderá encontrar: ![](chrome-tabs.svg) O painel *Sources* possui 3 partes: -1. O painel **File Navigator**, lista ficheiros de HTML, JavaScript, CSS e outros, incluindo imagens anexadas à página. Extensões ao Chrome (*Chrome extensions*) também podem aparecer aqui. -2. O painel **Code Editor**, mostra o código-fonte. -3. O painel **JavaScript Debugging**, é para a depuração de erros; iremos explorá-lo em breve. +1. O painel **Navegador de Arquivos** (*File Navigator*), lista arquivos HTML, JavaScript, CSS e outros. Inclui Imagens anexadas à página e Extensões do Google Chrome (*Chrome extensions*) também podem aparecer aqui. +2. O painel **Editor de Código** (*Code Editor*), mostra o código-fonte do arquivo selecionado. +3. O painel **Depuração do Javascript** (*JavaScript Debugging*) serve para a depuração de erros. Iremos explorá-lo em breve. -Agora, poderia clicar novamente no mesmo botão de alternador para ocultar a lista de recursos e dar ao código algum espaço. +Agora, é possível clicar novamente no mesmo botão de alternar para ocultar a lista de recursos e dar ao código algum espaço. -## Consola +## Console -Se pressionarmos `key:Esc`, uma consola se abre abaixo. Podemos aí digitar comandos e pressionar `key:Enter` para os executar. +Se pressionarmos `key:Esc`, um terminal (*Console*) se abrirá abaixo. Assim permitindo digitar instruções e executa-las pressionando `key:Enter`. -Depois de uma instrução ser executada, o seu resultado é mostrado abaixo. +Depois de uma instrução ser executada, o resultado será mostrado logo a seguir. -Por exemplo, aqui `1+2` resulta em `3`, e `hello("debugger")` não retorna nada, assim o seu resultado é `undefined`: +Por exemplo, a instrução `1+2` resultará em `3`, enquanto a chamada de função `hello("debugger")` não retornará nada, assim tendo como resultado `undefined`: ![](chrome-sources-console.svg) ## Breakpoints -Vamos examinar o que se passa dentro do código da [página exemplo](debugging/index.html). Em `hello.js`, clique no número de linha `4`. Sim, exatamente sobre o dígito `4`, não sobre o código. +Vamos examinar o que se passa dentro do código da [página exemplo](debugging/index.html). No arquivo `hello.js`, clique no número referente à linha `4`. Sim, exatamente sobre o dígito `4`, não sobre o código. -Parabéns! Estabeleceu um ponto-de-interrupção (*breakpoint*). Por favor, clique também no número de linha `8`. +Parabéns! Um ponto-de-interrupção (*breakpoint*) foi criado. Clique também no número referente a linha `8`, por favor. -Deveria se parecer com (a azul é onde deveria ter clicado): +Deve se parecer com isto (dígitos de cor azul é onde deveria ter clicado): ![](chrome-sources-breakpoint.svg) -Um *breakpoint* é um ponto no código onde o *debugger* (depurador de erros) irá automáticamente efetuar uma pausa na execução do JavaScript. +Um *breakpoint* é um ponto no código onde o depurador de erros (*debugger*) irá, automáticamente, efetuar uma pausa na execução do JavaScript. -Enquanto a execução do código estiver suspensa, podemos examinar variáveis correntes, executar comandos na consola, etc. Por outras palavras, podemos nele depurar erros (*debug it*). +Enquanto a execução do código estiver suspensa, é possível examinar valores de variáveis, executar comandos no terminal, etc. Em outras palavras, depurar erros (*debug it*). -Podemos sempre encontrar uma lista de *breakpoints* no painel à direita. É útil quando temos muitos *breakpoints* em vários ficheiros. Ela permite-nos: -- Rápidamente saltar para a linha do breakpoint no código (ao clicar sobre ele no painel à direita). -- Temporáriamente desativar o breakpoint, ao desmarcá-lo (*unchecking it*). -- Remover o breakpoint, clicando com o botão direito do rato e selecionando *Remove*. +Uma lista de *breakpoints* sempre estará disponível no painel à direita. Muito útil quando existem diferentes *breakpoints* em vários arquivos. Essa lista permite: +- Rápidamente saltar para a linha do *breakpoint* no código (ao clicar sobre ele no painel à direita). +- Temporáriamente desativar o *breakpoint* ao desmarcá-lo na caixinha seletora (*unchecking it*). +- Remover o breakpoint, clicando com o botão direito do mouse e selecionando *Remove*. - ...E assim por diante. ```smart header="*Breakpoints* condicionais" -*Clicando com o botão direito do rato* sobre um número de linha permite-nos criar um *breakpoint condicional*. Apenas será ativado quando a expressão inserida for verdadeira. +*Clicar com o botão direito do mouse* sobre um número de linha permite a criação de um *breakpoint condicional* o qual será ativado apenas quando a expressão inserida for verdadeira. -É prático quando apenas precisarmos de parar para um certo valor numa variável, ou para certos parâmetros numa função. +É prático quando precisamos de suspender a execução apenas para valores determinados de certa variável ou para parâmetros específicos numa função. ``` ## O comando *debugger* @@ -77,120 +77,119 @@ function hello(name) { let phrase = `Olá, ${name}!`; *!* - debugger; // <-- o *debugger* (depurador de erros) pára aqui + debugger; // <-- o *debugger* (depurador de erros) irá pausar a execução neste ponto. */!* say(phrase); } ``` -É muito conveniente quando estivermos num editor de código e não quisermos mudar para o navegador, e de seguida, nas ferramentas do desenvolvedor deste, procurar no programa (*script*) pelo local onde colocar o breakpoint. +Este comando só irá funcionar quando a interface de ferramentas de desenvolvedor do navegador estiver aberta, caso contrário, será ignorado. +## Pause e dê uma olhada -## Pause e dê uma vista de olhos +No nosso exemplo, a função `hello()` é chamada durante o carregamento da página, assim a forma mais fácil para ativar o *debugger* (depois de termos colocado os *breakpoints*) seria recarregar a página. Desta forma, vamos pressionar `key:F5` (Windows, Linux) ou `key:Cmd+R` (Mac). -No nosso exemplo, `hello()` é chamada durante o carregamento da página, assim a forma mais fácil para ativar o *debugger* (depois de termos colocado os *breakpoints*) é recarregar a página. Assim, vamos pressionar `key:F5` (Windows, Linux) ou `key:Cmd+R` (Mac). - -Como o breakpoint está estabelecido, é feita uma pausa na execução na quarta linha: +Após recarregar, como o breakpoint estará estabelecido, será feita uma pausa na execução na quarta linha: ![](chrome-sources-debugger-pause.svg) -Por favor, abra as secções de *dropdown* informacionais à direita (possuem etiquetas em seta). Elas permitem examinar o estado atual do código: +Por favor, abra as secções de *dropdown* informacionais à direita (apontadas pelas setas). Tais *dropdowns* permitem examinar o estado atual do código: -1. **`Watch` -- mostra valores correntes de expressões.** +1. **`Watch` -- mostra valores atuais das expressões.** - Pode clicar no mais `+` e inserir uma expressão. O *debugger* mostrará o seu valor em qualquer altura, e ele é automáticamente recalculado ao longo do processo de execução. + É possível clicar no `+` e inserir uma expressão. O *debugger* mostrará o valor da expressão e continuará recalculando-a ao longo do processo de execução. 2. **`Call Stack` -- mostra a sequência de chamadas de funções aninhadas.** - No presente momento, o *debugger* está dentro da chamada a `hello()`, invocada por código em `index.html` (não a partir de uma função, por isso o nome "*anonymous*" [anónimo]). + No presente momento, o *debugger* está dentro da chamada da função `hello()`, invocada por código em `index.html` (não a partir de uma função, por isso o nome "*anonymous*" [anónimo]). - Se clicar num item nessa pilha (*stack*) (por exemplo, em "*anonymous*"), o *debugger* saltará para o código correspondente, e todas as suas variáveis poderão ser igualmente examinadas. -3. **`Scope` -- variables atuais.** + Se clicar num item nessa pilha (*stack*) (por exemplo, em "*anonymous*"), o *debugger* saltará para o código correspondente e todas as suas variáveis poderão ser igualmente examinadas. +3. **`Scope` -- variáveis atuais.** - `Local` mostra variáveis locais de funções. Também, poderá ver os seus valores em destaque exatamente sobre o código-fonte. + `Local` mostra variáveis locais da função. Também será possível ver tais valores em destaque exatamente sobre o código-fonte. `Global` possui variáveis globais (aquelas fora de qualquer função). - Lá também existe a palavra-chave `this` que ainda não estudámos, mas o faremos em breve. + Lá também existe a palavra-chave `this` que ainda não estudámos mas o faremos em breve. ## Rastreando a execução -Agora, é altura para *rastrearmos* (*trace*) o código. +Agora, é o momento de *rastrearmos* (*trace*) o código. Existem botões para isso no topo do painel direito. Vamos interagir com eles. - -- "Resume": continue a execução, atalho (*hotkey*) `key:F8`. -: Retoma a execução. Se não houver *breakpoints* adicionais, a execução simplesmente prossegue e o *debugger* perde o controlo. + -- "Resume": continue executando, atalho (*hotkey*) `key:F8`. +: Retoma a execução. Se não houver *breakpoints* adicionais, a execução simplesmente prossegue e o *debugger* perde o controle. Aqui está o que poderemos ver após um clique sobre ele: ![](chrome-sources-debugger-trace-1.svg) - A execução prosseguiu, atingiu outro *breakpoint* dentro de `say()` e fez uma pausa lá. Dê uma vista de olhos sobre a "*Call stack*" à direita. Aumentou por mais uma chamada. Estamos dentro de `say()` agora. + A execução prosseguiu, atingiu outro *breakpoint* dentro da função `say()` e fez uma pausa lá. Dê uma olhada na "*Call stack*" à direita. Verá que aumentou por mais uma chamada. Estamos dentro da função `say()` agora. -- "Step": execute o próximo comando, atalho (*hotkey*) `key:F9`. : Executa a próxima instrução. Se o clicarmos agora, o `alert` será mostrado. Continuando a clicar nele, passará por todas as instruções do programa, uma por uma. - -- "Step over": execute o próximo comando, mas *mas não vá para dentro de uma função*, atalho `key:F10`. -: Similar ao comando "Step" anterior, mas com um comportamento diferente se a próxima instrução for uma chamada de função. Isto é: não uma incorporada (*built-in*), como `alert`, mas uma função nossa. + -- "Step over": execute o próximo comando, *mas não vá para dentro de uma função*, atalho `key:F10`. +: Similar ao comando "Step" anterior mas com um comportamento diferente se a próxima instrução for uma chamada de função. Isto é: não uma incorporada (*built-in*), como `alert`, mas uma função nossa. - O comando "Step", vai para dentro dela e suspende a execução na sua primeira linha, ao contrário de "Step over" que executa essa chamada de função aninhada invisívelmente, saltando sobre o funcionamento interno da função. + O comando "Step", vai para dentro dessa função e suspende a execução na sua primeira linha, ao contrário de "Step over" que executa essa chamada de função aninhada de forma invisível para nós, pulando todo seu funcionamento interno. É feita uma pausa na execução imediatamente depois dessa função. - É bom, se não estivermos interessados em ver o que acontece dentro da chamada de função. + É util quando não se está interessado em ver o que acontece dentro da chamada de uma função. -- "Step into", atalho `key:F11`. -: Similar a "Step", mas com um comportamento diferente no caso de chamadas de funções assíncronas. Se estiver a começar a aprender JavaScript, então poderá ignorar a diferença, porque ainda não temos chamadas assíncronas. +: Similar a "Step" mas com um comportamento diferente no caso de chamadas de funções assíncronas. Se estiver começando a aprender JavaScript, poderá ignorar a diferença porque ainda não vimos chamadas assíncronas. - Para o futuro, apenas tome nota que o comando "Step" ignora ações assíncronas, tais como `setTimeout` (chamada de função agendada), que são executadas mais tarde. O "Step into", vai para dentro dos seus códigos, esperando pela sua execução se necessário. Para mais detalhes, veja o [DevTools manual](https://developers.google.com/web/updates/2018/01/devtools#async). + Para o futuro, apenas tome nota que o comando "Step" ignora ações assíncronas, tais como `setTimeout` (chamada de função agendada), que são executadas mais tarde. O "Step into", vai para dentro do código destas funções assíncronas e aguarda a execução se necessário. Para mais detalhes, veja o [DevTools manual](https://developers.google.com/web/updates/2018/01/devtools#async). -- "Step out": continue a execução até ao fim da função atual, atalho `key:Shift+F11`. -: Continue a execução e a faça uma pausa na última linha da função atual. É útil quando acidentalmente entrámos para uma chamada aninhada usando , mas ela não nos interessa, e queremos prosseguir para o seu final o mais rápidamente possível. +: Continue a execução e faça uma pausa na última linha da função atual. É útil quando acidentalmente entrámos para uma chamada aninhada usando , porém, esta chamada aninhada não nos interessa e queremos prosseguir para o final desta função o mais rápido possível. - -- ative/desative todos os *breakpoints*. -: Esse botão não move a execução. Simplesmente liga/desliga *breakpoints* em grupo. + -- ativar/desativar todos os *breakpoints*. +: Esse botão não move a execução. Simplesmente ativa/desativa *breakpoints* em conjunto. - -- ative/desative a pausa automática em caso de erro. -: Quando ativo, e as ferramentas do desenvolvedor estiverem abertas, um erro no código automáticamente suspende a sua execução. Então, poderemos analisar variáveis para ver o que ocorreu de errado. Assim, se o código falhar por um erro, pode-se abrir o *debugger*, ativar esta opção e recarregar a página, afim de se observar onde falhou e qual o contexto nesse momento. + -- ativar/desativar a pausa automática em caso de erro. +: Quando ativo e as ferramentas do desenvolvedor abertas, um erro no código automáticamente suspende a execução do código. Assim permitindo a análise de variáveis para entender o que ocorreu de errado. Desta forma, se o código falhar por um erro, é possível abrir o *debugger*, ativar esta opção e recarregar a página afim de se observar onde e em que contexto a falha ocorreu. ```smart header="Continue até aqui" -Ao clicar com o botão direito do rato sobre uma linha de código, abre-se o menu de contexto com uma valiosa opção com o nome "Continue até aqui" (*Continue to here*). +Ao clicar com o botão direito do mouse sobre uma linha de código, abre-se o menu de contexto com uma ótima opção chamada "Continue até aqui" (*Continue to here*). -É prática quando quisermos mover adiante por múltiplos passos até essa linha, mas estamos preguiçosos demais para estabelecer um *breakpoint*. +É util quando se deseja avançar por múltiplos passos até aquela linha mas estamos preguiçosos demais para estabelecer um *breakpoint*. ``` ## Logging -Para mostrar na consola algo existente no código, existe a função `console.log`. +Para mostrar no terminal (*console*) algo existente no código, existe a função `console.log`. -Por exemplo, isto mostra os valores de `0` a `4` na consola: +Por exemplo, isto mostra os valores de `0` a `4` no *console*: ```js run -// abra a consola para visualizar +// abra o console para visualizar for (let i = 0; i < 5; i++) { console.log("valor,", i); } ``` -Utilizadores comuns não vêm essa saída (*output*), ela estará na consola. Para a ver, abra o separador Console nas ferramentas do desenvolvedor, ou pressione `key:Esc` se estiver num outro separador - isso abre a consola abaixo nesse separador. +Utilizadores comuns não enxergam essa saída (*output*), ela estará no console. Para vê-la, selecione a aba *console* nas ferramentas do desenvolvedor, ou pressione `key:Esc` se estiver em uma outra aba - isso abre o console abaixo na aba atual. -Se mostrarmos mensagens (*logging*) suficientes no nosso código, então poderemos ver o que nele se passa a partir desses registos, dispensando o *debugger*. +Se mostrarmos mensagens (*logging*) suficientes no nosso código, então poderemos ver o que nele se passa a partir desses registos, mesmo sem a utilização do *debugger*. ## Resumo -Como podemos ver, existem três formas principais para fazer uma pausa num *script*: +Como podemos ver, existem três formas principais para pausar a execução de um *script*: 1. Um *breakpoint* (ponto-de-interrupção). 2. As instruções `debugger`. 3. Um erro (se as ferramentas do desenvolvedor [*dev tools*] estiverem abertas, e o botão estiver "ativo"). -Enquanto suspenso, podemos depurar erros - examinar variáveis e rastear o código para ver onde a sua execução contém erros. +Enquanto suspenso, podemos depurar erros - examinar variáveis e rastear o código para ver que parte da execução ocorre com erros. -Existem muitas mais opções nas ferramentas do desenvolvedor do que as cobertas aqui. O manual completo está em . +Existem muitas outras opções nas ferramentas do desenvolvedor além das já cobertas ao longo desta leitura. O manual completo está em . -A informação neste capítulo é suficiente para iniciar a depuração de erros (o *debugging*), mas mais tarde, especialmente se trabalhar muito com o navegador (*browser*), por favor consulte o manual e procure por capacidades mais avançadas de ferramentas do desenvolvedor. +A informação neste capítulo é suficiente para iniciar a depuração de erros (o *debugging*), porém, especialmente se trabalhar muito com o navegador (*browser*), por favor consulte o manual e procure por recursos mais avançados das ferramentas do desenvolvedor. -Oh, também pode clicar em vários locais nas *dev tools* e ver o que acontece. Provávelmente, é a rota mais rápida para aprender sobre as *dev tools*. Não se esqueça de também clicar com o botão direito do rato e dos menus de contexto! +Oh, também é possível clicar em vários locais nas ferramentas do desenvolvedor (*dev tools*) e ver o que acontece. Provávelmente, é a rota mais rápida para aprender muitos dos recursos existentes. Não se esqueça de também clicar com o botão direito do mouse e dos menus de contexto!