Merge pull request #228 from xcurveballx/1/03/03-comments-fix-lex111

1/03/03 comments fix lex111

Author: javascript-translate-bot

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

@@ -1,6 +1,6 @@
 # Комментарии
 
-Как мы знаем из главы <info:structure>, комментарии могут быть однострочными, начинающимися с `//`, и многострочными: `/* ... */`.
+Как мы знаем из главы <info:structure>, комментарии могут быть однострочными, начинающимися с `//` и многострочными: `/* ... */`.
 
 Обычно мы их используем, чтобы описать, как и почему работает код.
 
@@ -43,7 +43,7 @@ function showPrimes(n) {
 }
 ```
 
-Лучший вариант, с использованием отдельной функции `isPrime`:
+Лучший вариант — использовать отдельную функцию `isPrime`:
 
 
 ```js
@@ -65,11 +65,11 @@ 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,8 +152,8 @@ function addJuice(container) {
 
     Без подобных комментариев возможна следующая ситуация:
     1. Вы (или ваш коллега) открываете написанный некоторое время назад код и видите, что в нём есть что улучшить.
-    2. Вы думаете: "Каким тупым я был раньше, и какой я умный сейчас", и переписываете его на "более правильный и оптимальный" вариант.
-    3. ...Желание переписать код -- это хорошо. Но в процессе вы понимаете, что "оптимальное" решение на самом деле не такое уж и оптимальное. Вы даже смутно припоминаете, почему, так как в прошлый раз вы уже его пробовали. Вы возвращаетесь к правильному варианту, потратив время зря.
+    2. Вы думаете: "Каким глупым я раньше был и насколько умнее стал сейчас", и переписываете его на "более правильный и оптимальный" вариант.
+    3. ...Желание переписать код -- это хорошо. Но в процессе вы понимаете, что "оптимальное" решение на самом деле не такое уж и оптимальное. Вы даже смутно припоминаете почему, так как в прошлый раз вы уже его пробовали. Вы возвращаетесь к правильному варианту, потратив время зря.
 
     Комментарии, объясняющие решение, очень важны. Они помогают продолжать разработку в правильном направлении.
 
@@ -170,11 +170,11 @@ function addJuice(container) {
 
 - Общую архитектуру, вид "с высоты птичьего полёта".
 - Использование функций.
-- Важные решения, особенно когда они неочевидны.
+- Важные решения, особенно когда они не очевидны на первый взгляд.
 
 **Избегайте комментариев:**
 
 - Которые объясняют, "как работает код" и "что он делает".
-- Используйте их только в тех случаях, когда невозможно сделать настолько простой и самодокументируемый код, который не потребует комментариев.
+- Используйте их только в тех случаях, когда невозможно сделать настолько простой и самодокументированный код, что он не потребует комментариев.
 
-Автодокументирующие инструменты, такие как JSDoc3, также используют комментарии: они их читают и генерируют HTML-документацию (или документацию в другом формате).
+Средства для генерации документации по коду, такие как JSDoc3, также используют комментарии: они их читают и генерируют HTML-документацию (или документацию в другом формате).