From 770ffb853c38859a70e10b17a93b837bc582c582 Mon Sep 17 00:00:00 2001 From: Arnau Roig Ninerola Date: Thu, 26 Sep 2019 18:50:30 +0200 Subject: [PATCH 01/21] Translated "Comments" to Spanish --- 1-js/03-code-quality/03-comments/article.md | 155 ++++++++++---------- 1 file changed, 77 insertions(+), 78 deletions(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 930ff929f..88bfae8b8 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -1,30 +1,30 @@ -# Comments +# Comentarios -As we know from the chapter , comments can be single-line: starting with `//` and multiline: `/* ... */`. +Como hemos aprendido en el cap�tulo , los comentarios pueden ser de una sola l�nea: comenzando con `//` y de m�ltiples l�neas: `/* ... */`. -We normally use them to describe how and why the code works. +Normalmente los usamos para describir c�mo y por qu� el c�digo funciona. -From the first sight, commenting might be obvious, but novices in programming usually get it wrong. +A primera vista, los comentarios pueden ser obvios, pero los principiantes en programaci�n generalmente los usan incorrectamente. -## Bad comments +## Comentarios incorrectos -Novices tend to use comments to explain "what is going on in the code". Like this: +Principiantes tienden a utilizar los comentarios para explicar "lo que est� pasando en el c�digo". As�: ```js -// This code will do this thing (...) and that thing (...) -// ...and who knows what else... -very; -complex; -code; +// Este c�digo har� esto (...) y esto (...) +// ...y qui�n sabe qu� m�s... +c�digo; +muy; +complejo; ``` -But in good code the amount of such "explanatory" comments should be minimal. Seriously, code should be easy to understand without them. +Pero en un buen c�digo, la cantidad de comentarios "explicativos" deber�a ser m�nima. En serio, el c�digo deber�a de ser f�cil de entender sin ellos. -There's a great rule about that: "if the code is so unclear that it requires a comment, then maybe it should be rewritten instead". +Existe una fant�stica regla al respeto: "si el c�digo es tan poco claro que necesita un comentario, entonces tal vez deber�a reescribirse en su lugar". -### Recipe: factor out functions +### Receta: funciones externas -Sometimes it's beneficial to replace a code piece with a function, like here: +A veces es beneficioso reemplazar trozos de c�digo con funciones, como aqu�: ```js function showPrimes(n) { @@ -32,7 +32,7 @@ function showPrimes(n) { for (let i = 2; i < n; i++) { *!* - // check if i is a prime number + // comprobar si i es un n�mero primo for (let j = 2; j < i; j++) { if (i % j == 0) continue nextPrime; } @@ -43,8 +43,7 @@ function showPrimes(n) { } ``` -The better variant, with a factored out function `isPrime`: - +La mejor variante, con una funci�n externa `isPrime`: ```js function showPrimes(n) { @@ -65,21 +64,21 @@ function isPrime(n) { } ``` -Now we can understand the code easily. The function itself becomes the comment. Such code is called *self-descriptive*. +Ahora podemos entender el c�digo f�cilmente. La propia funci�n se convierte en comentario. Este tipo de c�digo se le llama *auto descriptivo*. -### Recipe: create functions +### Receta: crear funciones -And if we have a long "code sheet" like this: +Y si tenemos una larga "hoja de c�digo" como esta: ```js -// here we add whiskey +// aqu� a�adimos whiskey for(let i = 0; i < 10; i++) { let drop = getWhiskey(); smell(drop); add(drop, glass); } -// here we add juice +// aqu� a�adimos zumo for(let t = 0; t < 3; t++) { let tomato = getTomato(); examine(tomato); @@ -90,7 +89,7 @@ for(let t = 0; t < 3; t++) { // ... ``` -Then it might be a better variant to refactor it into functions like: +Entonces, una versi�n mejor puede ser reescribirlo en funciones de esta manera: ```js addWhiskey(glass); @@ -111,70 +110,70 @@ function addJuice(container) { } ``` -Once again, functions themselves tell what's going on. There's nothing to comment. And also the code structure is better when split. It's clear what every function does, what it takes and what it returns. +De nuevo, la propias funciones nos dicen que est� pasando. No hay nada que comentar. Y adem�s, la estructura del c�digo es mejor cuando esta dividida. Queda claro que hace cada funci�n, que necesita y que retorna. -In reality, we can't totally avoid "explanatory" comments. There are complex algorithms. And there are smart "tweaks" for purposes of optimization. But generally we should try to keep the code simple and self-descriptive. +En realidad, no podemos evitar totalmente los comentarios "explicativos". Existen algoritmos complejos. Y existen "trucos" ingeniosos con el prop�sito de optimizar. Pero generalmente, tenemos que intentar mantener el c�digo simple y auto descriptivo. -## Good comments +## Comentarios correctos -So, explanatory comments are usually bad. Which comments are good? +Entonces, los comentarios explicativos suelen ser incorrectos.�Qu� comentarios son correctos? -Describe the architecture -: Provide a high-level overview of components, how they interact, what's the control flow in various situations... In short -- the bird's eye view of the code. There's a special diagram language [UML](http://wikipedia.org/wiki/Unified_Modeling_Language) for high-level architecture diagrams. Definitely worth studying. +Describe la arquitectura +: Proporcionan una descripci�n general de alto nivel de los componentes, c�mo interact�an, cual es el flujo de control en diversas situaciones... En resumen -- la vista panor�mica del c�digo. Hay un lenguaje de diagramas especial [UML](https://es.wikipedia.org/wiki/Lenguaje_unificado_de_modelado) para diagramas de alto nivel. Definitivamente vale la pena estudiarlo. -Document a function usage -: There's a special syntax [JSDoc](http://en.wikipedia.org/wiki/JSDoc) to document a function: usage, parameters, returned value. +Documenta la utilizaci�n de una funci�n +: Hay una sintaxis especial [JSDoc](https://en.wikipedia.org/wiki/JSDoc) para documentar una funci�n: utilizaci�n, par�metros, valor devuelto. - For instance: - ```js + Por ejemplo: + ```js /** - * Returns x raised to the n-th power. + * Devuelve x elevado a la potencia de n. * - * @param {number} x The number to raise. - * @param {number} n The power, must be a natural number. - * @return {number} x raised to the n-th power. + * @param {number} x El n�mero a elevar. + * @param {number} n La potencia, debe ser un n�mero natural. + * @return {number} x elevado a la potencia de n. */ function pow(x, n) { ... } ``` - - Such comments allow us to understand the purpose of the function and use it the right way without looking in its code. - - By the way, many editors like [WebStorm](https://www.jetbrains.com/webstorm/) can understand them as well and use them to provide autocomplete and some automatic code-checking. - - Also, there are tools like [JSDoc 3](https://github.com/jsdoc3/jsdoc) that can generate HTML-documentation from the comments. You can read more information about JSDoc at . - -Why is the task solved this way? -: What's written is important. But what's *not* written may be even more important to understand what's going on. Why is the task solved exactly this way? The code gives no answer. - - If there are many ways to solve the task, why this one? Especially when it's not the most obvious one. - - Without such comments the following situation is possible: - 1. You (or your colleague) open the code written some time ago, and see that it's "suboptimal". - 2. You think: "How stupid I was then, and how much smarter I'm now", and rewrite using the "more obvious and correct" variant. - 3. ...The urge to rewrite was good. But in the process you see that the "more obvious" solution is actually lacking. You even dimly remember why, because you already tried it long ago. You revert to the correct variant, but the time was wasted. - - Comments that explain the solution are very important. They help to continue development the right way. - -Any subtle features of the code? Where they are used? -: If the code has anything subtle and counter-intuitive, it's definitely worth commenting. - -## Summary - -An important sign of a good developer is comments: their presence and even their absence. - -Good comments allow us to maintain the code well, come back to it after a delay and use it more effectively. - -**Comment this:** - -- Overall architecture, high-level view. -- Function usage. -- Important solutions, especially when not immediately obvious. - -**Avoid comments:** - -- That tell "how code works" and "what it does". -- Put them only if it's impossible to make the code so simple and self-descriptive that it doesn't require those. - -Comments are also used for auto-documenting tools like JSDoc3: they read them and generate HTML-docs (or docs in another format). + + Estos tipos de comentarios nos permiten entender el prop�sito de la funci�n y como usarla de la manera correcta sin mirar su c�digo. + + Por cierto, muchos editores como [WebStorm](https://www.jetbrains.com/webstorm/) tambi�n pueden entenderlos y usarlos para proveer auto completado y alg�n tipo de verificaci�n autom�tica para el c�digo. + + Adem�s, existen herramientas como [JSDoc](https://github.com/jsdoc3/jsdoc) que pueden generar documentaci�n en formato HTML de los comentarios. Puedes leer m�s informaci�n sobre JSDoc aqu� . + +�Por qu� se resuelve de esa manera? +: Lo que est� escrito es importante. Pero lo que *no* est� escrito puede ser a�n m�s importante para entender que est� pasando. �Por qu� resuelven la tarea exactamente de esa manera? El c�digo no nos da ninguna respuesta. + + Si hay muchas maneras de resolver el problema, �por qu� esta? Especialmente cuando no es la m�s obvia. + + Sin dichos comentarios, las siguientes situaciones son posibles: + 1. Tu (o tu compa�ero) abres el c�digo escrito hace ya alg�n tiempo, y te das cuenta de que es "sub�ptimo". + 2. Piensas: "Que est�pido que era antes, y que inteligente que soy ahora", y lo reescribes utilizando la variante "m�s obvia y correcta". + 3. ...El impulso de reescribir era bueno. Pero en el proceso ves que la soluci�n "m�s obvia" en realidad falla. Incluso recuerdas vagamente el por qu�, por qu� ya lo intentaste hace mucho. Vuelves a la variante correcta pero has estado perdiendo el tiempo. + + Los comentarios que explican la soluci�n correcta son muy importantes. Nos ayudan a continuar el desarrollo de forma correcta. + +�Alguna caracter�stica sutil del c�digo? �Donde se usan? +: Si el c�digo tiene algo sutil y contra intuitivo, definitivamente vale la pena comentarlo. + +## Resumen + +Una se�al importante de un buen desarrollador son los comentarios: su presencia e incluso su ausencia. + +Los buenos comentarios nos permiten mantener bien el c�digo, volver despu�s de un retraso y usarlo de manera m�s efectiva. + +**Comenta esto:** + +- Arquitectura en general, vista de alto nivel. +- Utilizaci�n de funciones. +- Soluciones importantes, especialmente cuando no son inmediatamente obvias. + +**Evita comentarios:** + +- Que explican "como funciona el c�digo" y "que hace". +- Escribelos solo si es imposible escribir el c�digo de manera tan simple y auto descriptiva que no los necesite. + +Los comentarios tambi�n son usados para herramientas de auto documentaci�n como JSDoc3: los leen y generan documentaci�n en HTML (o documentos en otros formatos). From a4eac2eeea709aa66c8649289fb84c2c6c8cadea Mon Sep 17 00:00:00 2001 From: Arnau Roig Ninerola Date: Tue, 1 Oct 2019 14:05:41 +0200 Subject: [PATCH 02/21] Translated Polyfills and index.md to Spanish --- 1-js/03-code-quality/06-polyfills/article.md | 49 +++++++++----------- 1-js/03-code-quality/index.md | 4 +- 2 files changed, 24 insertions(+), 29 deletions(-) diff --git a/1-js/03-code-quality/06-polyfills/article.md b/1-js/03-code-quality/06-polyfills/article.md index 907730fdc..47b79060e 100644 --- a/1-js/03-code-quality/06-polyfills/article.md +++ b/1-js/03-code-quality/06-polyfills/article.md @@ -1,57 +1,52 @@ - # Polyfills -The JavaScript language steadily evolves. New proposals to the language appear regularly, they are analyzed and, if considered worthy, are appended to the list at and then progress to the [specification](http://www.ecma-international.org/publications/standards/Ecma-262.htm). +El lenguaje JavaScript evoluciona constantemente. Nuevas propuestas al lenguaje aparecen regularmente, son analizadas y, si se consideran valiosas, se agregan a la lista en y luego avanzan hasta [specification](http://www.ecma-international.org/publications/standards/Ecma-262.htm). -Teams behind JavaScript engines have their own ideas about what to implement first. They may decide to implement proposals that are in draft and postpone things that are already in the spec, because they are less interesting or just harder to do. +Equipos detr�s de int�rpretes (engines) de JavaScript tienen sus propias ideas sobre que implementar primero. Pueden decidir implementar propuestas que est�n en borrador y posponer cosas que ya est�n en la especificaci�n, por qu� son menos interesantes o simplemente m�s dif�ciles de hacer. -So it's quite common for an engine to implement only the part of the standard. +Por lo tanto, es bastante com�n para un int�rprete implementar solo la parte del est�ndar. -A good page to see the current state of support for language features is (it's big, we have a lot to study yet). +Una buena p�gina para ver el estado actual de soporte para caracter�sticas del lenguaje es (es grande, todav�a tenemos mucho que aprender). ## Babel -When we use modern features of the language, some engines may fail to support such code. Just as said, not all features are implemented everywhere. - -Here Babel comes to the rescue. +Cuando usamos caracter�sticas modernas del lenguaje, puede que algunos int�rpretes no soporten dicho c�digo. Como hemos dicho, no todas las caracter�sticas est�n implementadas en todas partes. -[Babel](https://babeljs.io) is a [transpiler](https://en.wikipedia.org/wiki/Source-to-source_compiler). It rewrites modern JavaScript code into the previous standard. +Aqu� Babel viene al rescate. -Actually, there are two parts in Babel: +[Babel](https://babeljs.io) es un [transpiler](https://en.wikipedia.org/wiki/Source-to-source_compiler). Reescribe c�digo JavaScript moderno en el est�ndar anterior. -1. First, the transpiler program, which rewrites the code. The developer runs it on their own computer. It rewrites the code into the older standard. And then the code is delivered to the website for users. Modern project build system like [webpack](http://webpack.github.io/) or [brunch](http://brunch.io/) provide means to run transpiler automatically on every code change, so that doesn't involve any time loss from our side. +En realidad, hay dos partes en Babel: -2. Second, the polyfill. +1. Primero, el programa transpiler, que reescribe c�digo. El desarrollador lo ejecuta en su propio ordenador. Reescribe el c�digo al viejo est�ndar. Y entonces el c�digo es entregado al navegador para los usuarios. Proyectos modernos para construcci�n de sistemas como [webpack](http://webpack.github.io/) o [brunch](http://brunch.io/), proporcionan medios para ejecutar el transpiler autom�ticamente en cada cambio al c�digo, de modo que no implique ninguna perdida de tiempo de nuestra parte. - The transpiler rewrites the code, so syntax features are covered. But for new functions we need to write a special script that implements them. JavaScript is a highly dynamic language, scripts may not just add new functions, but also modify built-in ones, so that they behave according to the modern standard. +2. Segundo, el polyfill. - There's a term "polyfill" for scripts that "fill in" the gap and add missing implementations. + El transpiler reescribe el c�digo, por lo que se cubren las caracter�sticas de la sintaxis. Pero para funciones nuevas tenemos que escribir un script especial que las implemente. JavaScript es un lenguaje muy din�mico, puede que los scripts no solo agreguen nuevas funciones, pero que tambi�n modifiquen las funciones incorporadas, para que act�en de forma correspondiente al est�ndar moderno. - Two interesting polyfills are: - - [babel polyfill](https://babeljs.io/docs/usage/polyfill/) that supports a lot, but is big. - - [polyfill.io](http://polyfill.io) service that allows to load/construct polyfills on-demand, depending on the features we need. + Existe el t�rmino "polyfill" para scripts que "llenan"(fill in) el vac�o y agregan las implementaciones que faltan. -So, we need to setup the transpiler and add the polyfill for old engines to support modern features. + Dos polyfills interesantes son: + - [babel polyfill](https://babeljs.io/docs/usage/polyfill/) que soporta mucho, pero es muy grande. + - [polyfill.io](http://polyfill.io) servicio que nos permite cargar/construir polyfills bajo demanda, dependiendo de las caracter�sticas que necesitemos. -If we orient towards modern engines and do not use features except those supported everywhere, then we don't need to use Babel. +As� que, si queremos usar caracter�sticas modernas del lenguaje, el transpiler y polyfill son necesarios. -## Examples in the tutorial +## Ejemplos en el tutorial ````online -Most examples are runnable at-place, like this: +La mayor�a de ejemplos se pueden ejecutar en el sitio, as�: ```js run -alert('Press the "Play" button in the upper-right corner to run'); +alert('Presione el bot�n "Play" en la esquina superior derecha para ejecutar'); ``` -Examples that use modern JS will work only if your browser supports it. +Ejemplos que usan JS moderno solo funcionar�n si tu navegador lo soporta. ```` ```offline -As you're reading the offline version, examples are not runnable. But they usually work :) +Como est�s leyendo la veri�n offline, en PDF los ejemplos no se pueden ejecutar. En EPUB algunos pueden ejecutarse. ``` -[Chrome Canary](https://www.google.com/chrome/browser/canary.html) is good for all examples, but other modern browsers are mostly fine too. - -Note that on production we can use Babel to translate the code into suitable for less recent browsers, so there will be no such limitation, the code will run everywhere. +Generalmente, Google Chrome est� actualizado con las �ltimas caracter�sticas del lenguaje, funciona bien para ejecutar demos con tecnolog�a puntera sin ning�n transpiler, pero otros navegadores modernos tambi�n funcionan bien. diff --git a/1-js/03-code-quality/index.md b/1-js/03-code-quality/index.md index 2ef64fa69..238778a10 100644 --- a/1-js/03-code-quality/index.md +++ b/1-js/03-code-quality/index.md @@ -1,3 +1,3 @@ -# Code quality +# Calidad del c�digo -This chapter explains coding practices that we'll use further in the development. +Este capitulo explica practicas en programaci�n que usaremos durante el desarrollo. From 4d59710f604d456a5cdeb8c0f9570fcd80229126 Mon Sep 17 00:00:00 2001 From: Arnau Roig Ninerola Date: Tue, 1 Oct 2019 15:48:45 +0200 Subject: [PATCH 03/21] Translated index.md --- 1-js/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/1-js/index.md b/1-js/index.md index c313cb85c..fc2840336 100644 --- a/1-js/index.md +++ b/1-js/index.md @@ -1,6 +1,6 @@ -# The JavaScript language +# El lenguaje JavaScript -Here we learn JavaScript, starting from scratch and go on to advanced concepts like OOP. +Aqu� aprendemos JavaScript, empezando desde zero y pasando a conceptos avanzados como OOP (programaci�n orientada a objetos). -We concentrate on the language itself here, with the minimum of environment-specific notes. +Aqu� nos concentramos en el lenguaje en si mismo, con el m�nimo de notas espec�ficas del entorno. From 1423018344bdfa54937d5f8178afd5409010ac6b Mon Sep 17 00:00:00 2001 From: joaquinelio Date: Sun, 7 Jun 2020 00:50:40 -0300 Subject: [PATCH 04/21] Update article.md --- 1-js/03-code-quality/03-comments/article.md | 86 ++++++++++----------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 81d18f29a..00b2e5add 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -1,30 +1,30 @@ # Comentarios -Como hemos aprendido en el cap�tulo , los comentarios pueden ser de una sola l�nea: comenzando con `//` y de m�ltiples l�neas: `/* ... */`. +Como hemos aprendido en el capítulo , los comentarios pueden ser de una sola línea: comenzando con `//` y de múltiples líneas: `/* ... */`. -Normalmente los usamos para describir c�mo y por qu� el c�digo funciona. +Normalmente los usamos para describir cómo y por qué el código funciona. -A primera vista, los comentarios pueden ser obvios, pero los principiantes en programaci�n generalmente los usan incorrectamente. +A primera vista, los comentarios pueden ser obvios, pero los principiantes en programación generalmente los usan incorrectamente. ## Comentarios incorrectos -Principiantes tienden a utilizar los comentarios para explicar "lo que est� pasando en el c�digo". As�: +Principiantes tienden a utilizar los comentarios para explicar "lo que está pasando en el código". Así: ```js -// Este c�digo har� esto (...) y esto (...) -// ...y qui�n sabe qu� m�s... -c�digo; +// Este código hará esto (...) y esto (...) +// ...y quién sabe qué más... +código; muy; complejo; ``` -Pero en un buen c�digo, la cantidad de comentarios "explicativos" deber�a ser m�nima. En serio, el c�digo deber�a de ser f�cil de entender sin ellos. +Pero en un buen código, la cantidad de comentarios "explicativos" debería ser mínima. En serio, el código debería de ser fácil de entender sin ellos. -Existe una fant�stica regla al respeto: "si el c�digo es tan poco claro que necesita un comentario, entonces tal vez deber�a reescribirse en su lugar". +Existe una fantástica regla al respeto: "si el código es tan poco claro que necesita un comentario, entonces tal vez debería reescribirse en su lugar". ### Receta: funciones externas -A veces es beneficioso reemplazar trozos de c�digo con funciones, como aqu�: +A veces es beneficioso reemplazar trozos de código con funciones, como aquí: ```js function showPrimes(n) { @@ -32,7 +32,7 @@ function showPrimes(n) { for (let i = 2; i < n; i++) { *!* - // comprobar si i es un n�mero primo + // comprobar si i es un número primo for (let j = 2; j < i; j++) { if (i % j == 0) continue nextPrime; } @@ -43,7 +43,7 @@ function showPrimes(n) { } ``` -La mejor variante, con una funci�n externa `isPrime`: +La mejor variante, con una función externa `isPrime`: ```js function showPrimes(n) { @@ -64,21 +64,21 @@ function isPrime(n) { } ``` -Ahora podemos entender el c�digo f�cilmente. La propia funci�n se convierte en comentario. Este tipo de c�digo se le llama *auto descriptivo*. +Ahora podemos entender el código fácilmente. La propia función se convierte en comentario. Este tipo de código se le llama *auto descriptivo*. ### Receta: crear funciones -Y si tenemos una larga "hoja de c�digo" como esta: +Y si tenemos una larga "hoja de código" como esta: ```js -// aqu� a�adimos whiskey +// aquí añadimos whiskey for(let i = 0; i < 10; i++) { let drop = getWhiskey(); smell(drop); add(drop, glass); } -// aqu� a�adimos zumo +// aquí añadimos zumo for(let t = 0; t < 3; t++) { let tomato = getTomato(); examine(tomato); @@ -89,7 +89,7 @@ for(let t = 0; t < 3; t++) { // ... ``` -Entonces, una versi�n mejor puede ser reescribirlo en funciones de esta manera: +Entonces, una versión mejor puede ser reescribirlo en funciones de esta manera: ```js addWhiskey(glass); @@ -110,27 +110,27 @@ function addJuice(container) { } ``` -De nuevo, la propias funciones nos dicen que est� pasando. No hay nada que comentar. Y adem�s, la estructura del c�digo es mejor cuando esta dividida. Queda claro que hace cada funci�n, que necesita y que retorna. +De nuevo, la propias funciones nos dicen que está pasando. No hay nada que comentar. Y además, la estructura del código es mejor cuando esta dividida. Queda claro que hace cada función, que necesita y que retorna. -En realidad, no podemos evitar totalmente los comentarios "explicativos". Existen algoritmos complejos. Y existen "trucos" ingeniosos con el prop�sito de optimizar. Pero generalmente, tenemos que intentar mantener el c�digo simple y auto descriptivo. +En realidad, no podemos evitar totalmente los comentarios "explicativos". Existen algoritmos complejos. Y existen "trucos" ingeniosos con el propósito de optimizar. Pero generalmente, tenemos que intentar mantener el código simple y auto descriptivo. ## Comentarios correctos -Entonces, los comentarios explicativos suelen ser incorrectos.�Qu� comentarios son correctos? +Entonces, los comentarios explicativos suelen ser incorrectos¿Qué comentarios son correctos? Describe la arquitectura -: Proporcionan una descripci�n general de alto nivel de los componentes, c�mo interact�an, cual es el flujo de control en diversas situaciones... En resumen -- la vista panor�mica del c�digo. Hay un lenguaje de diagramas especial [UML](https://es.wikipedia.org/wiki/Lenguaje_unificado_de_modelado) para diagramas de alto nivel. Definitivamente vale la pena estudiarlo. +: Proporcionan una descripción general de alto nivel de los componentes, cómo interactúan, cual es el flujo de control en diversas situaciones... En resumen -- la vista panorámica del código. Hay un lenguaje de diagramas especial [UML](https://es.wikipedia.org/wiki/Lenguaje_unificado_de_modelado) para diagramas de alto nivel. Definitivamente vale la pena estudiarlo. -Documenta la utilizaci�n de una funci�n -: Hay una sintaxis especial [JSDoc](https://en.wikipedia.org/wiki/JSDoc) para documentar una funci�n: utilizaci�n, par�metros, valor devuelto. +Documenta la utilización de una función +: Hay una sintaxis especial [JSDoc](https://en.wikipedia.org/wiki/JSDoc) para documentar una función: utilización, parámetros, valor devuelto. Por ejemplo: ```js /** * Devuelve x elevado a la potencia de n. * - * @param {number} x El n�mero a elevar. - * @param {number} n La potencia, debe ser un n�mero natural. + * @param {number} x El número a elevar. + * @param {number} n La potencia, debe ser un número natural. * @return {number} x elevado a la potencia de n. */ function pow(x, n) { @@ -138,42 +138,42 @@ Documenta la utilizaci�n de una funci�n } ``` - Estos tipos de comentarios nos permiten entender el prop�sito de la funci�n y como usarla de la manera correcta sin mirar su c�digo. + Estos tipos de comentarios nos permiten entender el propósito de la función y como usarla de la manera correcta sin mirar su código. - Por cierto, muchos editores como [WebStorm](https://www.jetbrains.com/webstorm/) tambi�n pueden entenderlos y usarlos para proveer auto completado y alg�n tipo de verificaci�n autom�tica para el c�digo. + Por cierto, muchos editores como [WebStorm](https://www.jetbrains.com/webstorm/) también pueden entenderlos y usarlos para proveer auto completado y algún tipo de verificación automática para el código. - Adem�s, existen herramientas como [JSDoc](https://github.com/jsdoc3/jsdoc) que pueden generar documentaci�n en formato HTML de los comentarios. Puedes leer m�s informaci�n sobre JSDoc aqu� . + Además, existen herramientas como [JSDoc](https://github.com/jsdoc3/jsdoc) que pueden generar documentación en formato HTML de los comentarios. Puedes leer más información sobre JSDoc aquí . -�Por qu� se resuelve de esa manera? -: Lo que est� escrito es importante. Pero lo que *no* est� escrito puede ser a�n m�s importante para entender que est� pasando. �Por qu� resuelven la tarea exactamente de esa manera? El c�digo no nos da ninguna respuesta. +¿Por qué se resuelve de esa manera? +: Lo que está escrito es importante. Pero lo que *no* está escrito puede ser aún más importante para entender que está pasando. ¿Por qué resuelven la tarea exactamente de esa manera? El código no nos da ninguna respuesta. - Si hay muchas maneras de resolver el problema, �por qu� esta? Especialmente cuando no es la m�s obvia. + Si hay muchas maneras de resolver el problema, ¿por qué esta? Especialmente cuando no es la más obvia. Sin dichos comentarios, las siguientes situaciones son posibles: - 1. Tu (o tu compa�ero) abres el c�digo escrito hace ya alg�n tiempo, y te das cuenta de que es "sub�ptimo". - 2. Piensas: "Que est�pido que era antes, y que inteligente que soy ahora", y lo reescribes utilizando la variante "m�s obvia y correcta". - 3. ...El impulso de reescribir era bueno. Pero en el proceso ves que la soluci�n "m�s obvia" en realidad falla. Incluso recuerdas vagamente el por qu�, por qu� ya lo intentaste hace mucho. Vuelves a la variante correcta pero has estado perdiendo el tiempo. + 1. Tu (o tu compañero) abres el código escrito hace ya algún tiempo, y te das cuenta de que es "subóptimo". + 2. Piensas: "Que estúpido que era antes, y que inteligente que soy ahora", y lo reescribes utilizando la variante "más obvia y correcta". + 3. ...El impulso de reescribir era bueno. Pero en el proceso ves que la solución "más obvia" en realidad falla. Incluso recuerdas vagamente el por qué por qué ya lo intentaste hace mucho. Vuelves a la variante correcta pero has estado perdiendo el tiempo. - Los comentarios que explican la soluci�n correcta son muy importantes. Nos ayudan a continuar el desarrollo de forma correcta. + Los comentarios que explican la solución correcta son muy importantes. Nos ayudan a continuar el desarrollo de forma correcta. -�Alguna caracter�stica sutil del c�digo? �Donde se usan? -: Si el c�digo tiene algo sutil y contra intuitivo, definitivamente vale la pena comentarlo. +¿Alguna característica sutil del código? ¿Donde se usan? +: Si el código tiene algo sutil y contra intuitivo, definitivamente vale la pena comentarlo. ## Resumen -Una se�al importante de un buen desarrollador son los comentarios: su presencia e incluso su ausencia. +Una señal importante de un buen desarrollador son los comentarios: su presencia e incluso su ausencia. -Los buenos comentarios nos permiten mantener bien el c�digo, volver despu�s de un retraso y usarlo de manera m�s efectiva. +Los buenos comentarios nos permiten mantener bien el código, volver después de un retraso y usarlo de manera más efectiva. **Comenta esto:** - Arquitectura en general, vista de alto nivel. -- Utilizaci�n de funciones. +- Utilización de funciones. - Soluciones importantes, especialmente cuando no son inmediatamente obvias. **Evita comentarios:** -- Que explican "como funciona el c�digo" y "que hace". -- Escribelos solo si es imposible escribir el c�digo de manera tan simple y auto descriptiva que no los necesite. +- Que explican "como funciona el código" y "que hace". +- Escribelos solo si es imposible escribir el código de manera tan simple y auto descriptiva que no los necesite. -Los comentarios tambi�n son usados para herramientas de auto documentaci�n como JSDoc3: los leen y generan documentaci�n en HTML (o documentos en otros formatos). +Los comentarios también son usados para herramientas de auto documentación como JSDoc3: los leen y generan documentación en HTML (o documentos en otros formatos). From 3f24e451ff9e35a73b83040aa04f3222d6fcdd23 Mon Sep 17 00:00:00 2001 From: joaquinelio Date: Sun, 7 Jun 2020 01:31:55 -0300 Subject: [PATCH 05/21] Update article.md --- 1-js/03-code-quality/06-polyfills/article.md | 32 ++++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/1-js/03-code-quality/06-polyfills/article.md b/1-js/03-code-quality/06-polyfills/article.md index aba3d2252..0bef1b449 100644 --- a/1-js/03-code-quality/06-polyfills/article.md +++ b/1-js/03-code-quality/06-polyfills/article.md @@ -2,51 +2,51 @@ El lenguaje JavaScript evoluciona constantemente. Nuevas propuestas al lenguaje aparecen regularmente, son analizadas y, si se consideran valiosas, se agregan a la lista en y luego avanzan hasta [specification](http://www.ecma-international.org/publications/standards/Ecma-262.htm). -Equipos detr�s de int�rpretes (engines) de JavaScript tienen sus propias ideas sobre que implementar primero. Pueden decidir implementar propuestas que est�n en borrador y posponer cosas que ya est�n en la especificaci�n, por qu� son menos interesantes o simplemente m�s dif�ciles de hacer. +Equipos detrás de intérpretes (engines) de JavaScript tienen sus propias ideas sobre que implementar primero. Pueden decidir implementar propuestas que están en borrador y posponer cosas que ya están en la especificación, por qué son menos interesantes o simplemente más difíciles de hacer. -Por lo tanto, es bastante com�n para un int�rprete implementar solo la parte del est�ndar. +Por lo tanto, es bastante común para un intérprete implementar solo la parte del estándar. -Una buena p�gina para ver el estado actual de soporte para caracter�sticas del lenguaje es (es grande, todav�a tenemos mucho que aprender). +Una buena página para ver el estado actual de soporte para características del lenguaje es (es grande, todavía tenemos mucho que aprender). ## Babel -Cuando usamos caracter�sticas modernas del lenguaje, puede que algunos int�rpretes no soporten dicho c�digo. Como hemos dicho, no todas las caracter�sticas est�n implementadas en todas partes. +Cuando usamos características modernas del lenguaje, puede que algunos intérpretes no soporten dicho código. Como hemos dicho, no todas las características están implementadas en todas partes. -Aqu� Babel viene al rescate. +Aquí Babel viene al rescate. -[Babel](https://babeljs.io) es un [transpiler](https://en.wikipedia.org/wiki/Source-to-source_compiler). Reescribe c�digo JavaScript moderno en el est�ndar anterior. +[Babel](https://babeljs.io) es un [transpiler](https://en.wikipedia.org/wiki/Source-to-source_compiler). Reescribe código JavaScript moderno en el estándar anterior. En realidad, hay dos partes en Babel: -1. Primero, el programa transpiler, que reescribe c�digo. El desarrollador lo ejecuta en su propio ordenador. Reescribe el c�digo al viejo est�ndar. Y entonces el c�digo es entregado al navegador para los usuarios. Proyectos modernos para construcci�n de sistemas como [webpack](http://webpack.github.io/) o [brunch](http://brunch.io/), proporcionan medios para ejecutar el transpiler autom�ticamente en cada cambio al c�digo, de modo que no implique ninguna perdida de tiempo de nuestra parte. +1. Primero, el programa transpiler, que reescribe código. El desarrollador lo ejecuta en su propio ordenador. Reescribe el código al viejo estándar. Y entonces el código es entregado al navegador para los usuarios. Proyectos modernos para construcción de sistemas como [webpack](http://webpack.github.io/) o [brunch](http://brunch.io/), proporcionan medios para ejecutar el transpiler automáticamente en cada cambio al código, de modo que no implique ninguna perdida de tiempo de nuestra parte. 2. Segundo, el polyfill. - El transpiler reescribe el c�digo, por lo que se cubren las caracter�sticas de la sintaxis. Pero para funciones nuevas tenemos que escribir un script especial que las implemente. JavaScript es un lenguaje muy din�mico, puede que los scripts no solo agreguen nuevas funciones, pero que tambi�n modifiquen las funciones incorporadas, para que act�en de forma correspondiente al est�ndar moderno. + El transpiler reescribe el código, por lo que se cubren las características de la sintaxis. Pero para funciones nuevas tenemos que escribir un script especial que las implemente. JavaScript es un lenguaje muy dinámico, puede que los scripts no solo agreguen nuevas funciones, pero que también modifiquen las funciones incorporadas, para que actúen de forma correspondiente al estándar moderno. - Existe el t�rmino "polyfill" para scripts que "llenan"(fill in) el vac�o y agregan las implementaciones que faltan. + Existe el término "polyfill" para scripts que "llenan"(fill in) el vacío y agregan las implementaciones que faltan. Dos polyfills interesantes son: - [babel polyfill](https://babeljs.io/docs/usage/polyfill/) que soporta mucho, pero es muy grande. - - [polyfill.io](http://polyfill.io) servicio que nos permite cargar/construir polyfills bajo demanda, dependiendo de las caracter�sticas que necesitemos. + - [polyfill.io](http://polyfill.io) servicio que nos permite cargar/construir polyfills bajo demanda, dependiendo de las características que necesitemos. -As� que, si queremos usar caracter�sticas modernas del lenguaje, el transpiler y polyfill son necesarios. +Así que, si queremos usar características modernas del lenguaje, el transpiler y polyfill son necesarios. ## Ejemplos en el tutorial ````online -La mayor�a de ejemplos se pueden ejecutar en el sitio, as�: +La mayoría de ejemplos se pueden ejecutar en el sitio, así: ```js run -alert('Presione el bot�n "Play" en la esquina superior derecha para ejecutar'); +alert('Presione el botón "Play" en la esquina superior derecha para ejecutar'); ``` -Ejemplos que usan JS moderno solo funcionar�n si tu navegador lo soporta. +Ejemplos que usan JS moderno solo funcionarán si tu navegador lo soporta. ```` ```offline -Como est�s leyendo la veri�n offline, en PDF los ejemplos no se pueden ejecutar. En EPUB algunos pueden ejecutarse. +Como estás leyendo la verión offline, en PDF los ejemplos no se pueden ejecutar. En EPUB algunos pueden ejecutarse. ``` -Generalmente, Google Chrome est� actualizado con las �ltimas caracter�sticas del lenguaje, funciona bien para ejecutar demos con tecnolog�a puntera sin ning�n transpiler, pero otros navegadores modernos tambi�n funcionan bien. +Generalmente, Google Chrome está actualizado con las últimas características del lenguaje, funciona bien para ejecutar demos con tecnología puntera sin ningún transpiler, pero otros navegadores modernos también funcionan bien. From 600defa9e416f8bb5806f082dc34e9c93e567e07 Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:30:42 -0400 Subject: [PATCH 06/21] Update 1-js/03-code-quality/06-polyfills/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/06-polyfills/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/06-polyfills/article.md b/1-js/03-code-quality/06-polyfills/article.md index 0bef1b449..754f9cf13 100644 --- a/1-js/03-code-quality/06-polyfills/article.md +++ b/1-js/03-code-quality/06-polyfills/article.md @@ -22,7 +22,7 @@ En realidad, hay dos partes en Babel: 2. Segundo, el polyfill. - El transpiler reescribe el código, por lo que se cubren las características de la sintaxis. Pero para funciones nuevas tenemos que escribir un script especial que las implemente. JavaScript es un lenguaje muy dinámico, puede que los scripts no solo agreguen nuevas funciones, pero que también modifiquen las funciones incorporadas, para que actúen de forma correspondiente al estándar moderno. + El transpiler reescribe el código, por lo que se cubren las características de la sintaxis. Pero para funciones nuevas tenemos que escribir un script especial que las implemente. JavaScript es un lenguaje muy dinámico, puede que los scripts no solo agreguen nuevas funciones, sino también modifiquen las funciones incorporadas, para que actúen de forma correspondiente al estándar moderno. Existe el término "polyfill" para scripts que "llenan"(fill in) el vacío y agregan las implementaciones que faltan. From ecf907a4a2137ffd706a565ef105978dc3bb6651 Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:31:02 -0400 Subject: [PATCH 07/21] Update 1-js/03-code-quality/06-polyfills/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/06-polyfills/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/06-polyfills/article.md b/1-js/03-code-quality/06-polyfills/article.md index 754f9cf13..66fd41f72 100644 --- a/1-js/03-code-quality/06-polyfills/article.md +++ b/1-js/03-code-quality/06-polyfills/article.md @@ -2,7 +2,7 @@ El lenguaje JavaScript evoluciona constantemente. Nuevas propuestas al lenguaje aparecen regularmente, son analizadas y, si se consideran valiosas, se agregan a la lista en y luego avanzan hasta [specification](http://www.ecma-international.org/publications/standards/Ecma-262.htm). -Equipos detrás de intérpretes (engines) de JavaScript tienen sus propias ideas sobre que implementar primero. Pueden decidir implementar propuestas que están en borrador y posponer cosas que ya están en la especificación, por qué son menos interesantes o simplemente más difíciles de hacer. +Equipos detrás de intérpretes (engines) de JavaScript tienen sus propias ideas sobre qué implementar primero. Pueden decidir implementar propuestas que están en borrador y posponer cosas que ya están en la especificación, porque son menos interesantes o simplemente más difíciles de hacer. Por lo tanto, es bastante común para un intérprete implementar solo la parte del estándar. From a8338d6046e356b943fbd14ff49e1f9d36761566 Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:31:27 -0400 Subject: [PATCH 08/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 00b2e5add..bed7abb5b 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -174,6 +174,6 @@ Los buenos comentarios nos permiten mantener bien el código, volver después de **Evita comentarios:** - Que explican "como funciona el código" y "que hace". -- Escribelos solo si es imposible escribir el código de manera tan simple y auto descriptiva que no los necesite. +- Escríbelos solo si es imposible escribir el código de manera tan simple y auto descriptiva que no los necesite. Los comentarios también son usados para herramientas de auto documentación como JSDoc3: los leen y generan documentación en HTML (o documentos en otros formatos). From 82a7ad93c39c34476fd5adc0d7afbbb4b1189bfc Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:31:41 -0400 Subject: [PATCH 09/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index bed7abb5b..57a676d8f 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -173,7 +173,7 @@ Los buenos comentarios nos permiten mantener bien el código, volver después de **Evita comentarios:** -- Que explican "como funciona el código" y "que hace". +- Que explican "cómo funciona el código" y "qué hace". - Escríbelos solo si es imposible escribir el código de manera tan simple y auto descriptiva que no los necesite. Los comentarios también son usados para herramientas de auto documentación como JSDoc3: los leen y generan documentación en HTML (o documentos en otros formatos). From 4e61df3b90dd51b93c49208cac2b761af8406e5d Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:31:55 -0400 Subject: [PATCH 10/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 57a676d8f..1fab1f08d 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -157,7 +157,7 @@ Documenta la utilización de una función Los comentarios que explican la solución correcta son muy importantes. Nos ayudan a continuar el desarrollo de forma correcta. ¿Alguna característica sutil del código? ¿Donde se usan? -: Si el código tiene algo sutil y contra intuitivo, definitivamente vale la pena comentarlo. +: Si el código tiene algo sutil y contraintuitivo, definitivamente vale la pena comentarlo. ## Resumen From 57488032617500170518d26285e3eb015b51702f Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:32:17 -0400 Subject: [PATCH 11/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 1fab1f08d..19e587a9a 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -156,7 +156,7 @@ Documenta la utilización de una función Los comentarios que explican la solución correcta son muy importantes. Nos ayudan a continuar el desarrollo de forma correcta. -¿Alguna característica sutil del código? ¿Donde se usan? +¿Alguna característica sutil del código? ¿Dónde se usan? : Si el código tiene algo sutil y contraintuitivo, definitivamente vale la pena comentarlo. ## Resumen From 94502aa50e433d54e4b2fe49a50608a10f9b697a Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:32:39 -0400 Subject: [PATCH 12/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 19e587a9a..b66f65f04 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -152,7 +152,7 @@ Documenta la utilización de una función Sin dichos comentarios, las siguientes situaciones son posibles: 1. Tu (o tu compañero) abres el código escrito hace ya algún tiempo, y te das cuenta de que es "subóptimo". 2. Piensas: "Que estúpido que era antes, y que inteligente que soy ahora", y lo reescribes utilizando la variante "más obvia y correcta". - 3. ...El impulso de reescribir era bueno. Pero en el proceso ves que la solución "más obvia" en realidad falla. Incluso recuerdas vagamente el por qué por qué ya lo intentaste hace mucho. Vuelves a la variante correcta pero has estado perdiendo el tiempo. + 3. ...El impulso de reescribir era bueno. Pero en el proceso ves que la solución "más obvia" en realidad falla. Incluso recuerdas vagamente el porqué, porque ya lo intentaste hace mucho. Vuelves a la variante correcta pero has estado perdiendo el tiempo. Los comentarios que explican la solución correcta son muy importantes. Nos ayudan a continuar el desarrollo de forma correcta. From 121ea66b50c74a707a17ac1ae0dfbc85e894c951 Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:33:02 -0400 Subject: [PATCH 13/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index b66f65f04..6000c7c8d 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -116,7 +116,7 @@ En realidad, no podemos evitar totalmente los comentarios "explicativos". Existe ## Comentarios correctos -Entonces, los comentarios explicativos suelen ser incorrectos¿Qué comentarios son correctos? +Entonces, los comentarios explicativos suelen ser incorrectos. ¿Qué comentarios son correctos? Describe la arquitectura : Proporcionan una descripción general de alto nivel de los componentes, cómo interactúan, cual es el flujo de control en diversas situaciones... En resumen -- la vista panorámica del código. Hay un lenguaje de diagramas especial [UML](https://es.wikipedia.org/wiki/Lenguaje_unificado_de_modelado) para diagramas de alto nivel. Definitivamente vale la pena estudiarlo. From e0991ffcbfddd566f02a043c966b629f6b996884 Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:33:22 -0400 Subject: [PATCH 14/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 6000c7c8d..20c27114d 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -150,7 +150,7 @@ Documenta la utilización de una función Si hay muchas maneras de resolver el problema, ¿por qué esta? Especialmente cuando no es la más obvia. Sin dichos comentarios, las siguientes situaciones son posibles: - 1. Tu (o tu compañero) abres el código escrito hace ya algún tiempo, y te das cuenta de que es "subóptimo". + 1. Tú (o tu compañero) abres el código escrito hace ya algún tiempo, y te das cuenta de que es "subóptimo". 2. Piensas: "Que estúpido que era antes, y que inteligente que soy ahora", y lo reescribes utilizando la variante "más obvia y correcta". 3. ...El impulso de reescribir era bueno. Pero en el proceso ves que la solución "más obvia" en realidad falla. Incluso recuerdas vagamente el porqué, porque ya lo intentaste hace mucho. Vuelves a la variante correcta pero has estado perdiendo el tiempo. From b8cb7addf4acf366a519c10f9d78af81a53bb056 Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:33:42 -0400 Subject: [PATCH 15/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 20c27114d..4c11a9cb4 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -145,7 +145,7 @@ Documenta la utilización de una función Además, existen herramientas como [JSDoc](https://github.com/jsdoc3/jsdoc) que pueden generar documentación en formato HTML de los comentarios. Puedes leer más información sobre JSDoc aquí . ¿Por qué se resuelve de esa manera? -: Lo que está escrito es importante. Pero lo que *no* está escrito puede ser aún más importante para entender que está pasando. ¿Por qué resuelven la tarea exactamente de esa manera? El código no nos da ninguna respuesta. +: Lo que está escrito es importante. Pero lo que *no* está escrito puede ser aún más importante para entender qué está pasando. ¿Por qué resuelven la tarea exactamente de esa manera? El código no nos da ninguna respuesta. Si hay muchas maneras de resolver el problema, ¿por qué esta? Especialmente cuando no es la más obvia. From a177987f868ee4ca642be3ee122274e0c58f0fb5 Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:33:59 -0400 Subject: [PATCH 16/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 4c11a9cb4..fef8f2b67 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -138,7 +138,7 @@ Documenta la utilización de una función } ``` - Estos tipos de comentarios nos permiten entender el propósito de la función y como usarla de la manera correcta sin mirar su código. + Estos tipos de comentarios nos permiten entender el propósito de la función y cómo usarla de la manera correcta sin mirar su código. Por cierto, muchos editores como [WebStorm](https://www.jetbrains.com/webstorm/) también pueden entenderlos y usarlos para proveer auto completado y algún tipo de verificación automática para el código. From 3596a2d8175363da8626305e9ef201f8daa0e439 Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:34:14 -0400 Subject: [PATCH 17/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index fef8f2b67..da135af58 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -119,7 +119,7 @@ En realidad, no podemos evitar totalmente los comentarios "explicativos". Existe Entonces, los comentarios explicativos suelen ser incorrectos. ¿Qué comentarios son correctos? Describe la arquitectura -: Proporcionan una descripción general de alto nivel de los componentes, cómo interactúan, cual es el flujo de control en diversas situaciones... En resumen -- la vista panorámica del código. Hay un lenguaje de diagramas especial [UML](https://es.wikipedia.org/wiki/Lenguaje_unificado_de_modelado) para diagramas de alto nivel. Definitivamente vale la pena estudiarlo. +: Proporcionan una descripción general de alto nivel de los componentes, cómo interactúan, cuál es el flujo de control en diversas situaciones... En resumen -- la vista panorámica del código. Hay un lenguaje de diagramas especial [UML](https://es.wikipedia.org/wiki/Lenguaje_unificado_de_modelado) para diagramas de alto nivel. Definitivamente vale la pena estudiarlo. Documenta la utilización de una función : Hay una sintaxis especial [JSDoc](https://en.wikipedia.org/wiki/JSDoc) para documentar una función: utilización, parámetros, valor devuelto. From b60d1daad2e283c6fefdfd1038db26f9f23468a4 Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:34:23 -0400 Subject: [PATCH 18/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index da135af58..d9489cb65 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -110,7 +110,7 @@ function addJuice(container) { } ``` -De nuevo, la propias funciones nos dicen que está pasando. No hay nada que comentar. Y además, la estructura del código es mejor cuando esta dividida. Queda claro que hace cada función, que necesita y que retorna. +De nuevo, la propias funciones nos dicen qué está pasando. No hay nada que comentar. Y además, la estructura del código es mejor cuando está dividida. Queda claro qué hace cada función, qué necesita y qué retorna. En realidad, no podemos evitar totalmente los comentarios "explicativos". Existen algoritmos complejos. Y existen "trucos" ingeniosos con el propósito de optimizar. Pero generalmente, tenemos que intentar mantener el código simple y auto descriptivo. From 4705c46d4c02ebe3db09cb1ca76427fe48fca484 Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:34:34 -0400 Subject: [PATCH 19/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index d9489cb65..1f45dc944 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -20,7 +20,7 @@ complejo; Pero en un buen código, la cantidad de comentarios "explicativos" debería ser mínima. En serio, el código debería de ser fácil de entender sin ellos. -Existe una fantástica regla al respeto: "si el código es tan poco claro que necesita un comentario, entonces tal vez debería reescribirse en su lugar". +Existe una fantástica regla al respeto: "si el código es tan poco claro que necesita un comentario, tal vez en su lugar debería ser reescrito.". ### Receta: funciones externas From 3b79f5b7172bb70a73a1ad16da82113cb4e79d29 Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:34:52 -0400 Subject: [PATCH 20/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 1f45dc944..1ec85d75f 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -18,7 +18,7 @@ muy; complejo; ``` -Pero en un buen código, la cantidad de comentarios "explicativos" debería ser mínima. En serio, el código debería de ser fácil de entender sin ellos. +Pero en un buen código, la cantidad de comentarios "explicativos" debería ser mínima. En serio, el código debería ser fácil de entender sin ellos. Existe una fantástica regla al respeto: "si el código es tan poco claro que necesita un comentario, tal vez en su lugar debería ser reescrito.". From a4f4473116e0dcdd1f7e1c2a36db3c1dbbc61043 Mon Sep 17 00:00:00 2001 From: Valentina VP <34555644+vplentinax@users.noreply.github.com> Date: Sun, 7 Jun 2020 14:35:08 -0400 Subject: [PATCH 21/21] Update 1-js/03-code-quality/03-comments/article.md Co-authored-by: joaquinelio --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 1ec85d75f..54e62fdb8 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -8,7 +8,7 @@ A primera vista, los comentarios pueden ser obvios, pero los principiantes en pr ## Comentarios incorrectos -Principiantes tienden a utilizar los comentarios para explicar "lo que está pasando en el código". Así: +Los rincipiantes tienden a utilizar los comentarios para explicar "lo que está pasando en el código". Así: ```js // Este código hará esto (...) y esto (...)