Правки lex111 по PR 108

Author: xcurveballx

1-js/03-code-quality/03-comments/article.md

@@ -43,7 +43,7 @@ function showPrimes(n) {
 }
 ```
 
-Лучший вариант, с использованием отдельной функции `isPrime`:
+Лучший вариант — использовать отдельную функцию `isPrime`:
 
 
 ```js
@@ -69,7 +69,7 @@ function isPrime(n) {
 
 ### Рецепт: создавайте функции
 
-И если мы имеем длинный кусок кода:
+И если мы имеем такой длинный кусок кода:
 
 ```js
 // здесь мы добавляем виски
@@ -113,7 +113,7 @@ function addJuice(container) {
 
 Ещё раз, функции сами по себе описывают, что в них происходит. Тут нечего комментировать. И ещё, структура кода лучше, когда она разделена на части. Понятно, что делает каждая функция, что она принимает и что возвращает.
 
-В реальности мы не можем полностью избежать "объясняющих" комментариев. Существуют сложные алгоритмы. И есть хитрые "твики" для их оптимизации. Но в целом мы должны стараться писать простой и самодокументируемый код.
+В реальности мы не можем полностью избежать "объясняющих" комментариев. Существуют сложные алгоритмы. И есть хитрые уловки для их оптимизации. Но в целом мы должны стараться писать простой и самодокументируемый код.
 
 ## Хорошие комментарии
 
@@ -130,8 +130,8 @@ function addJuice(container) {
     /**
      * Возвращает x, возведённое в n-ную степень.
      *
-     * @param {number} x Возводимое в степерь число.
-     * @param {number} n Степерь, должна быть натуральным числом.
+     * @param {number} x Возводимое в степень число.
+     * @param {number} n Степень, должна быть натуральным числом.
      * @return {number} x, возведённое в n-ную степень.
      */
     function pow(x, n) {
@@ -141,7 +141,7 @@ function addJuice(container) {
 
     Подобные комментарии позволяют нам понимать назначение функции и правильно её использовать без необходимости заглядывать в код.
 
-    Кстати, многие редакторы, такие как [WebStorm](https://www.jetbrains.com/webstorm/), прекрасно их понимают и используют для обеспечения функции автозавершения и некоторых автоматических проверок кода.
+    Кстати, многие редакторы, такие как [WebStorm](https://www.jetbrains.com/webstorm/), прекрасно их распознают для того, чтобы выполнить автодополнение ввода и различные автоматические проверки кода.
 
     Также существуют инструменты, например, [JSDoc 3](https://github.com/jsdoc3/jsdoc), которые умеют генерировать HTML-документацию из комментариев. Получить больше информации о JSDoc вы можете здесь: <http://usejsdoc.org/>.
 
@@ -152,13 +152,13 @@ function addJuice(container) {
 
     Без подобных комментариев возможна следующая ситуация:
     1. Вы (или ваш коллега) открываете написанный некоторое время назад код и видите, что в нём есть что улучшить.
-    2. Вы думаете: "Каким тупым я был раньше, и какой я умный сейчас", и переписываете его на "более правильный и оптимальный" вариант.
+    2. Вы думаете: "Каким глупым я раньше был и насколько умнее стал сейчас", и переписываете его на "более правильный и оптимальный" вариант.
     3. ...Желание переписать код -- это хорошо. Но в процессе вы понимаете, что "оптимальное" решение на самом деле не такое уж и оптимальное. Вы даже смутно припоминаете, почему, так как в прошлый раз вы уже его пробовали. Вы возвращаетесь к правильному варианту, потратив время зря.
 
     Комментарии, объясняющие решение, очень важны. Они помогают продолжать разработку в правильном направлении.
 
 В коде есть какие-то тонкости? Где они используются?
-: Если в коде есть какие-то тонкости и неочевидные вещи, его определённо нужно комментировать.
+: Если в коде есть что-то неочевидное или нелогичное, то такие места определённо нужно комментировать.
 
 ## Итого
 
@@ -170,7 +170,7 @@ function addJuice(container) {
 
 - Общую архитектуру, вид "с высоты птичьего полёта".
 - Использование функций.
-- Важные решения, особенно когда они неочевидны.
+- Важные решения, особенно когда они не очевидны на первый взгляд.
 
 **Избегайте комментариев:**