update content

Signed-off-by: Kirill Mokevnin <mokevnin@gmail.com>

Author: mokevnin

modules/10-basics/10-hello-world/ru/README.md

@@ -1,44 +1,60 @@
-![Hello World](./assets/hello-world.png)
-
-Изучение нового языка программирования традиционно начинается с 'Hello, World!'. Это простая программа, которая выводит приветствие на экран и заодно знакомит с новым языком — его синтаксисом и структурой программы.
+Изучение нового языка программирования традиционно начинается с программы 'Hello, World!'. Это простая программа, которая выводит приветствие на экран и знакомит с синтаксисом и структурой нового языка.
 
 ```text
 Hello, World!
 ```
 
-Этой традиции уже больше сорока лет, поэтому и мы не будем нарушать ее. В первом уроке мы напишем программу `Hello, World!`. На Python это программа выглядит так:
+![Hello World](./assets/hello-world.png)
+
+
+Этой традиции уже больше сорока лет, и мы тоже начнем с нее. В первом уроке мы напишем программу `Hello, World!`. На Python это программа выглядит так:
 
 ```python
 print('Hello, World!')
 ```
 
-`print()` — это команда, которая работает по определённому шаблону: в скобках указывается текст для вывода на экран. Мы можем передавать туда любой другой текст.
-
-```text
-  Код              Интерпретатор         Экран
-  ┌──────────┐     ┌─────────────┐     ┌──────────────┐
-  │ print(…) │ ──→ │   Python    │ ──→ │ Hello, World!│
-  └──────────┘     └─────────────┘     └──────────────┘
-```
+Команда `print()` выводит на экран текст, указанный в скобках. Вместо примера можно написать любой другой текст.
 
 ```python
 print('Хекслет - школа программирования')
 ```
 
-Команда остаётся той же, меняется только содержимое скобок. Чтобы программа понимала, что это именно текст, он заключается в кавычки. Можно использовать одинарные `'...'` или двойные `"..."`, главное — чтобы открывающая и закрывающая кавычки совпадали.
+Команда остается той же, меняется только содержимое скобок. Чтобы программа понимала, что это именно текст, он заключается в кавычки. Можно использовать одинарные `'...'` или двойные `"..."`, но открывающая и закрывающая кавычки должны совпадать.
 
 ```python
 print("Хекслет - школа программирования")
 ```
 
-По принятому в Python стандарту оформления кода (PEP 8) рекомендуется использовать одинарные кавычки для строк, если внутри них нет апострофа. Это делает код более единообразным.
+По принятому в Python стандарту оформления кода (PEP 8) рекомендуется использовать одинарные кавычки для строк. Если внутри строки есть апостроф, одинарные кавычки сломают синтаксис, поэтому в таких случаях используют двойные.
+
+```python
+print("it's a Python")  # апостроф внутри, поэтому двойные кавычки
+```
 
 ## Значение символов
 
-Программирование — это не просто текст на английском. Код состоит из команд, и каждая из них должна быть написана в определённой форме. Для этого используются не только буквы, но и специальные символы: кавычки `'` и `"`, скобки `()`, запятая `,`, восклицательный знак `!`. Они не случайные — каждый символ имеет своё значение. Если пропустить знак или перепутать его, программа не запустится.
+Код состоит из команд, и каждая из них должна быть написана в определенной форме. Помимо букв, в коде важны кавычки `'` и `"`, скобки `()` и знаки препинания. Пропущенный или перепутанный знак приведет к тому, что программа не запустится. Попробуйте определить, какая ошибка допущено в каждой из строк?
+
+```python
+print("it's a Python"
+print(it's a Python")
+prin("it's a Python")
+print('it's a Python")
+prInt("it's a Python")
+```
 
-Даже небольшое отличие, например одна лишняя буква или другой знак, может привести к тому, что программа не будет работать. Это относится и к такому понятию, как регистр — различию между большими и маленькими буквами. Если в обычном тексте `Привет` и `привет` выглядят одинаково, то для Python (как и других языков) это разные слова. Поэтому `print`, `Print` и `PRINT` — это разные команды, и сработает только первый вариант.
+Даже небольшое отличие, например одна лишняя буква или другой знак, может привести к тому, что программа не будет работать. Это относится и к регистру, то есть к различию между большими и маленькими буквами. Если в обычном тексте `Привет` и `привет` выглядят одинаково, то для Python это разные слова. Python считает `print`, `Print` и `PRINT` разными командами, и сработает только первый вариант.
 
 ## Где практиковаться
 
-Обучение программированию происходит эффективнее, когда помимо чтения теории и выполнении заданий, вы будете практиковаться вызывая код в специальной среде (интерактивная оболочка или REPL), где можно выполнять код на Python построчно. Регулярно повторяйте все что вы видите в уроке [в интерактивной консоли Python](https://pyodide.org/en/stable/console.html)
+Теория усваивается лучше, когда параллельно запускаешь код и видишь результат. Для этого подходит интерактивная оболочка Python (REPL), где команды выполняются построчно. Все, что встречается в уроке, стоит пробовать [в интерактивной консоли Python](https://pyodide.org/en/stable/console.html).
+
+Как это работает технически? Любой написанный код передается в интерпретатор Python, который этот код выполняет и выводит на экран результат его работы.
+
+```text
+  Код              Интерпретатор         Экран
+  ┌──────────┐     ┌─────────────┐     ┌──────────────┐
+  │ print(…) │ ──→ │   Python    │ ──→ │ Hello, World!│
+  └──────────┘     └─────────────┘     └──────────────┘
+```
+

modules/10-basics/20-comments/index.py

@@ -1 +1 @@
-# You know nothing, Jon Snow!
+# TODO: добавить функцию приветствия

modules/10-basics/20-comments/ru/EXERCISE.md

@@ -1 +1,3 @@
-Создайте комментарий с текстом: `You know nothing, Jon Snow!`
+Добавьте в файл TODO-комментарий с текстом: `TODO: добавить функцию приветствия`
+
+Такие комментарии помечают место в коде, которое нужно доработать позже. Это один из самых распространенных видов комментариев в реальных проектах.

modules/10-basics/20-comments/ru/README.md

@@ -1,16 +1,16 @@
-Кроме самого кода, в исходных файлах часто можно встретить комментарии — это строки, которые не обрабатываются интерпретатором. Они нужны для программистов: чтобы пояснить, как работает код, отметить, где есть ошибки, или напомнить себе и другим, что нужно доделать.
+Кроме самого кода, в исходных файлах часто можно встретить комментарии. Это строки, которые интерпретатор не обрабатывает. Программисты пишут их, чтобы пояснить, как работает код, отметить ошибки или напомнить, что нужно доделать.
 
 ```python
 # Удалить строку ниже после реализации задачи по регистрации
 print(10)
 ```
 
-В Python все комментарии — однострочные. Они начинаются со специального символа #, после которого может идти любой текст. Всё, что написано после #, интерпретатор игнорирует.
+В Python все комментарии однострочные. Они начинаются со специального символа #, после которого может идти любой текст. Все, что написано после #, интерпретатор игнорирует.
 
 ```text
   # комментарий   ──→  [ пропущено интерпретатором ]
   print('hello')  ──→  [ выполнено → hello ]
-  # ещё один      ──→  [ пропущено интерпретатором ]
+  # еще один      ──→  [ пропущено интерпретатором ]
 ```
 
 Комментарий может занимать всю строку:
@@ -34,9 +34,7 @@ print('I am the King') # For Lannisters!
 print('I am the King')
 ```
 
-Они не влияют на выполнение программы, но делают код понятнее. Комментарии помогают команде быстрее разобраться в чужом коде и не забыть важные детали в собственном.
-
->  Хорошее правило: пишите код так, чтобы он был понятен без комментариев, но если что-то требует пояснения — не стесняйтесь комментировать.
+Интерпретатор игнорирует комментарии. Разработчики благодаря им быстрее разбираются в чужом коде и не забывают важные детали в собственном.
 
 ## Служебные комментарии
 
@@ -48,12 +46,12 @@ print('I am the King')
 # END
 ```
 
-*BEGIN* и *END* здесь это обычные комментарии, которые никак не влияют на работу программы. Они нужны для того, чтобы показать место, где нужно писать код задания - между ними.
+*BEGIN* и *END* здесь это обычные комментарии, которые никак не влияют на работу программы. Они показывают, куда писать код задания.
 
 ```python
 # BEGIN
 <здесь ваше решение>
 # END
 ```
 
-Проще говоря: видите *BEGIN* и *END* — пишите между ними, остальное не трогайте.
+Увидев *BEGIN* и *END*, пишите свой код между ними, остальное оставляйте без изменений.

modules/10-basics/20-comments/test_code.py

@@ -1,5 +1,5 @@
 def test():
     with open("index.py") as file:
         comment = file.read().rstrip()
-        assert comment == "# You know nothing, Jon Snow!"
+        assert comment == "# TODO: добавить функцию приветствия"
         print(comment)

modules/10-basics/30-instructions/index.py

@@ -1,3 +1,3 @@
-print("Robert")
-print("Stannis")
-print("Renly")
+print("Заказ №1337")
+print("Статус: доставляется")
+print("Примерный срок: 2 дня")

modules/10-basics/30-instructions/ru/EXERCISE.md

@@ -1,9 +1,7 @@
-Выведите на экран друг за другом три имени: *Robert*, *Stannis*, *Renly*. В результате на экране должно отобразиться:
+Выведите на экран статус доставки посылки — три строки, каждая отдельным вызовом `print()`:
 
 ```text
-Robert
-Stannis
-Renly
+Заказ №1337
+Статус: доставляется
+Примерный срок: 2 дня
 ```
-
-Для каждого имени используйте свой собственный вызов `print()`.

modules/10-basics/30-instructions/ru/README.md

@@ -1,8 +1,4 @@
-![Инструкции](./assets/instructions.png)
-
-Когда мы готовим блюдо, то следуем рецепту шаг за шагом. Пропустим этап — и результат будет отличаться от ожидаемого. В программировании работает тот же принцип: чёткий порядок инструкций определяет, как работает программа.
-
-Инструкция (или оператор) — это команда для компьютера. Она говорит: «сделай что-то прямо сейчас». Интерпретатор Python (специальная программа, которая понимает и выполняет код) выполняет код сверху вниз, по строкам. Он обрабатывает каждую инструкцию по очереди, как если бы читал рецепт по шагам.
+Команду `print('Hexlet')` мы можем назвать инструкцией, она говорит интерпретатору Python что нужно делать. Таких инструкций может быть сколько угодно. Каждая из них выполняется после того, как закончилась предыдущая и так мы из простых элементов получаем сколь угодно большую и сложную программу.
 
 ```text
   Инструкция 1: print('Hello')   →  выполнена
@@ -12,7 +8,7 @@
   Инструкция 3: print('!')       →  выполнена
 ```
 
-Вот пример кода с двумя инструкциями. Эти строки говорят компьютеру: «Выведи фразу на экран».
+Вот пример кода с двумя инструкциями. Эти строки говорят компьютеру вывести фразы на экран.
 
 ```python
 print('Mother of Dragons.') # Первая инструкция
@@ -28,14 +24,14 @@ Dracarys!
 
 ## Порядок имеет значение
 
-Интерпретатор Python исполняет код в строгом порядке — как вы его написали. Если поменять местами строки:
+Интерпретатор Python выполняет код строго в том порядке, в котором вы его написали. Если поменять строки местами:
 
 ```python
 print('Dracarys!')
 print('Mother of Dragons.')
 ```
 
-то и на экране они поменяются:
+на экране они тоже поменяются:
 
 ```text
 Dracarys!
@@ -44,10 +40,30 @@ Mother of Dragons.
 
 ## Альтернативная форма записи
 
-Обычно инструкции пишутся на отдельных строках, но Python допускает объединение нескольких инструкций в одну строку с помощью ;:
+Обычно инструкции пишут на отдельных строках, но Python позволяет объединить несколько инструкций в одну строку с помощью `;`:
 
 ```python
 print('Mother of Dragons.'); print('Dracarys!');
 ```
 
-Обе версии работают одинаково, но второй вариант хуже читается. В реальных проектах принято писать инструкции построчно — это повышает читаемость и упрощает поддержку кода.
+Обе версии работают одинаково, но второй вариант читать сложнее. Поэтому инструкции почти всегда пишут по одной на строку.
+
+## Зачем это нужно
+
+Сейчас мы пишем очень простые программы, но со временем они начнут усложняться и один из самых важных навыков, который поможет их понимать, это способность разбивать (в голове) программу на независимые инструкции. Только так можно разобраться в том, что в коде происходит. Ниже пример для привлечения внимание, понимать его пока не надо:
+
+```python
+def is_prime(number: int) -> bool:
+    if number < 2:
+        return False
+
+    divider = 2
+
+    while divider <= number / 2:
+        if number % divider == 0:
+            return False
+
+        divider += 1
+
+    return True
+```

modules/10-basics/30-instructions/test_code.py

@@ -2,5 +2,5 @@
 
 
 def test(capsys):
-    expected = "Robert\nStannis\nRenly"
+    expected = "Заказ №1337\nСтатус: доставляется\nПримерный срок: 2 дня"
     expect_output(capsys, expected)