Правки curveball по PR 108

Author: xcurveballx

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

@@ -1,6 +1,6 @@
 # Комментарии
 
-Как мы знаем из главы <info:structure>, комментарии могут быть однострочными, начинающимися с `//`, и многострочными: `/* ... */`.
+Как мы знаем из главы <info:structure>, комментарии могут быть однострочными, начинающимися с `//` и многострочными: `/* ... */`.
 
 Обычно мы их используем, чтобы описать, как и почему работает код.
 
@@ -65,7 +65,7 @@ function isPrime(n) {
 }
 ```
 
-Теперь мы можем легко понять код. Функция сама становится комментарием. Такой код называется *самодокументируемым*.
+Теперь мы можем легко понять код. Функция сама становится комментарием. Такой код называется *самоописательным*.
 
 ### Рецепт: создавайте функции
 
@@ -113,7 +113,7 @@ function addJuice(container) {
 
 Ещё раз, функции сами по себе описывают, что в них происходит. Тут нечего комментировать. И ещё, структура кода лучше, когда она разделена на части. Понятно, что делает каждая функция, что она принимает и что возвращает.
 
-В реальности мы не можем полностью избежать "объясняющих" комментариев. Существуют сложные алгоритмы. И есть хитрые уловки для их оптимизации. Но в целом мы должны стараться писать простой и самодокументируемый код.
+В реальности мы не можем полностью избежать "объясняющих" комментариев. Существуют сложные алгоритмы. И есть хитрые уловки для оптимизации. Но в целом мы должны стараться писать простой и самоописательный код.
 
 ## Хорошие комментарии
 
@@ -153,7 +153,7 @@ function addJuice(container) {
     Без подобных комментариев возможна следующая ситуация:
     1. Вы (или ваш коллега) открываете написанный некоторое время назад код и видите, что в нём есть что улучшить.
     2. Вы думаете: "Каким глупым я раньше был и насколько умнее стал сейчас", и переписываете его на "более правильный и оптимальный" вариант.
-    3. ...Желание переписать код -- это хорошо. Но в процессе вы понимаете, что "оптимальное" решение на самом деле не такое уж и оптимальное. Вы даже смутно припоминаете, почему, так как в прошлый раз вы уже его пробовали. Вы возвращаетесь к правильному варианту, потратив время зря.
+    3. ...Желание переписать код -- это хорошо. Но в процессе вы понимаете, что "оптимальное" решение на самом деле не такое уж и оптимальное. Вы даже смутно припоминаете почему, так как в прошлый раз вы уже его пробовали. Вы возвращаетесь к правильному варианту, потратив время зря.
 
     Комментарии, объясняющие решение, очень важны. Они помогают продолжать разработку в правильном направлении.
 
@@ -175,6 +175,6 @@ function addJuice(container) {
 **Избегайте комментариев:**
 
 - Которые объясняют, "как работает код" и "что он делает".
-- Используйте их только в тех случаях, когда невозможно сделать настолько простой и самодокументируемый код, который не потребует комментариев.
+- Используйте их только в тех случаях, когда невозможно сделать настолько простой и самоописательный код, что он не потребует комментариев.
 
 Автодокументирующие инструменты, такие как JSDoc3, также используют комментарии: они их читают и генерируют HTML-документацию (или документацию в другом формате).