update first module

Signed-off-by: Kirill Mokevnin <[email protected]>

Author: mokevnin

.markdownlint.json

@@ -1,3 +1,6 @@
 {
-  "MD013": false
+  "MD013": false,
+  "MD033": false,
+  "MD041": false,
+  "MD040": false
 }

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

@@ -1,2 +1 @@
-
-Создайте однострочный комментарий с текстом: `You know nothing, Jon Snow!`
+Создайте комментарий с текстом: `You know nothing, Jon Snow!`

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

@@ -1,22 +1,33 @@
-
-Практически все языки программирования позволяют оставлять в коде комментарии. Они никак не используются интерпретатором. Они нужны исключительно для людей, чтобы программист оставлял пометки для себя и для других программистов.
-
-С их помощью добавляют пояснения, как работает код, какие ошибки нужно поправить или не забыть что-то добавить позже:
+Кроме самого кода, в исходных файлах часто можно встретить комментарии — это строки, которые не обрабатываются интерпретатором. Они нужны для программистов: чтобы пояснить, как работает код, отметить, где есть ошибки, или напомнить себе и другим, что нужно доделать.
 
 ```python
 # Удалить строку ниже после реализации задачи по регистрации
 print(10)
 ```
 
-Комментарии в Python начинаются со знака `#` и могут появляться в любом месте программы. Они могут занимать всю строку. Если одной строки мало, то создается несколько комментариев:
+В Python все комментарии — однострочные. Они начинаются со специального символа #, после которого может идти любой текст. Всё, что написано после #, интерпретатор игнорирует.
+
+Комментарий может занимать всю строку:
 
 ```python
 # For Winterfell!
 # For Lanisters!
 ```
 
-Комментарий может находиться на строке после кода:
+Или стоять в конце строки с кодом:
 
 ```python
 print('I am the King') # For Lannisters!
 ```
+
+Если нужно оставить длинное пояснение, используют несколько строк с #:
+
+```python
+# The night is dark and
+# full of terrors.
+print('I am the King')
+```
+
+Они не влияют на выполнение программы, но делают код понятнее. Комментарии помогают команде быстрее разобраться в чужом коде и не забыть важные детали в собственном.
+
+> 📌 Хорошее правило: пишите код так, чтобы он был понятен без комментариев, но если что-то требует пояснения — не стесняйтесь комментировать.

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

@@ -1,28 +1,50 @@
-Когда мы готовим блюдо, то четко следуем рецепту. Иначе еда окажется не такой, как ожидали. Это же правило действует и в программировании.
+Когда мы готовим блюдо, то следуем рецепту шаг за шагом. Пропустим этап — и результат будет отличаться от ожидаемого. В программировании работает тот же принцип: чёткий порядок инструкций определяет, как работает программа.
 
-Чтобы увидеть на экране ожидаемый результат, нужно дать компьютеру четкие и пошаговые указания. Это можно сделать с помощью инструкций. Инструкция — это команда для компьютера, единица выполнения. Код на Python в этом случае — это набор инструкций. Его можно представить в виде пошагового рецепта.
+Инструкция (или оператор) — это команда для компьютера. Она говорит: «сделай что-то прямо сейчас».
 
-Код на Python запускает **интерпретатор** — программу, которая выполняет инструкции строго по очереди. Как и шаги в рецепте, набор инструкций для интерпретатора пишутся по порядку и отделяются друг от друга переходом на следующую строку.
+В Python программа состоит из инструкций — отдельных команд, которые выполняются компьютером. Это как пошаговый рецепт: одна строка — один шаг.
 
-Разработчики должны понимать порядок действий в коде и уметь мысленно разделять программу на независимые части, удобные для анализа.
+Интерпретатор Python (специальная программа, которая понимает и выполняет код) выполняет код сверху вниз, по строкам. Он обрабатывает каждую инструкцию по очереди, как если бы читал рецепт по шагам.
 
-Посмотрим на пример кода с двумя инструкциями. При его запуске на экран последовательно выводятся два предложения:
+Вот пример кода с двумя инструкциями:
 
-```python
-print('Mother of Dragons.')
-print('Dracarys!')
-# => Mother of Dragons.
-# => Dracarys!
+```Python
+print('Mother of Dragons.') # Первая инструкция
+print('Dracarys!') # Вторая инструкция
 ```
 
-https://replit.com/@hexlet/python-basics-instructions
+💡 Эти строки говорят компьютеру: «Выведи фразу на экран».
+
+Результат выполнения:
 
-Выше мы говорили, что инструкции отделяются друг от друга переходом на новую строку. Но есть и другой способ: их можно разделить точкой с запятой — `;`:
+<pre class='hexlet-basics-output'>
+  Mother of Dragons.
+  Dracarys!
+</pre>
 
-```python
-print('Mother of Dragons.'); print('Drakarys!')
+## Порядок имеет значение
+
+Интерпретатор Python исполняет код в строгом порядке — как вы его написали.
+Если поменять местами строки:
+
+```Python
+print('Dracarys!')
+print('Mother of Dragons.')
 ```
 
-Технической разницы между первым и вторым вариантом нет — интерпретатор поймет инструкции одинаково. Разница только в том, что человеку будет неудобно читать второй вариант.
+то и на экране они поменяются:
+
+<pre class='hexlet-basics-output'>
+  Mother of Dragons.
+  Dracarys!
+</pre>
+
+## Альтернативная форма записи
+
+Обычно инструкции пишутся на отдельных строках, но Python допускает объединение нескольких инструкций в одну строку с помощью ;:
+
+```Python
+print('Mother of Dragons.'); print('Dracarys!')
+```
 
-Лучше инструкции располагать друг под другом. Так коллегам будет удобнее читать ваш код, обслуживать его и вносить изменения.
+Обе версии работают одинаково, но второй вариант хуже читается. В реальных проектах принято писать инструкции построчно — это повышает читаемость и упрощает поддержку кода.

modules/10-basics/40-testing/ru/EXERCISE.md

@@ -1 +1 @@
-Выведите на экран `9780262531962`.
+Выведите на экран `9780262531962` используя `print()`.

modules/10-basics/40-testing/ru/README.md

@@ -1,4 +1,3 @@
-
 Наш сайт автоматически проверяет ваши решения. Как это работает?
 
 В самом простом случае система просто запускает ваш код и смотрит на то, что вывелось на экран. А потом сверяет с тем, что мы «ожидали» по заданию.
@@ -17,10 +16,12 @@
 
 Самое главное начинается после двоеточия: «значение "10" не равно ожидаемому значению "35"». То есть правильная функция должна была выдать 35, но текущее решение работает неправильно и выдаёт 10.
 
-Ещё стоит отметить, что если вы видите, что в редакторе уже присутствует какой-то код, а вместе с ним комментарии `BEGIN` и `END`, то обычно это подразумевает, что вам нужно писать ваш код между этими самыми BEGIN и END! Код, данный вам заранее, трогать не стоит: это может повлиять на проверку правильности решения. Проще говоря: видите строчки с комментариями `BEGIN` и `END` — пишите свой код между ними!
+Если в редакторе уже есть какой-то код, окружённый комментариями *BEGIN* и *END*, это означает, что свой код нужно писать строго между ними. Код за пределами этих комментариев менять не стоит — это может повлиять на корректность проверки.
+
+Проще говоря: видите *BEGIN* и *END* — пишите между ними, остальное не трогайте.
 
----
+## Мой ошибка или нет?
 
 Иногда в процессе решения будет казаться, что вы сделали все правильно, но система "капризничает" и не принимает решение. Подобное поведение практически исключено. Нерабочие тесты просто не могут попасть на сайт, они автоматически запускаются после каждого изменения. В подавляющем большинстве таких случаев, (а все наши проекты в сумме провели миллионы проверок за много лет), ошибка содержится в коде решения. Она может быть очень незаметной, вместо английской буквы случайно ввели русскую, вместо верхнего регистра использовали нижний или забыли вывести запятую. Другие случаи сложнее. Возможно ваше решение работает для одного набора входных данных, но не работает для другого. Поэтому всегда внимательно читайте условие задачи и вывод тестов. Там почти наверняка есть указание на ошибку.
 
-Однако, если вы уверены в ошибке или нашли какую-то неточность, то вы всегда можете указать на нее. В конце каждой теории есть ссылка на содержимое урока на гитхабе (этот проект полностью открытый!). Перейдя туда, вы можете написать issue, посмотреть содержимое тестов (там видно, как вызывается ваш код) и даже отправить pullrequest. Если для вас это пока темный лес, то подключитесь в наше [сообщество в Telegram](https://t.me/hexletcommunity/3), там в канале *'Обратная связь'* мы всегда поможем.
+Однако, если вы уверены в ошибке или нашли какую-то неточность, то вы всегда можете указать на нее в нашем [сообществе](https://ttttt.me/HexletLearningBot), там в канале _'Обратная связь'_ мы всегда поможем.

modules/10-basics/50-syntax-errors/ru/EXERCISE.md

@@ -1,4 +1,3 @@
-
 Это задание не связано с уроком напрямую. Но будет полезным потренироваться с выводом на экран.
 
 Выведите на экран:

modules/10-basics/50-syntax-errors/ru/README.md

@@ -1,17 +1,22 @@
+Если программа на Python написана с нарушением правил, интерпретатор остановит выполнение и выведет сообщение об ошибке. В этом сообщении указывается:
 
-Если программа на Python написана синтаксически некорректно, то интерпретатор выводит на экран соответствующее сообщение. Также он указывает на файл и строчку, где произошла ошибка.
+- Тип ошибки,
+- строка, в которой она произошла,
+- и (часто) точка, где интерпретатор «споткнулся».
 
-**Синтаксическая ошибка** возникает в том случае, когда код записали с нарушением грамматических правил. В естественных языках грамматика важна, но текст с ошибками обычно можно понять и прочитать. В программировании все строго. Мельчайшее нарушение — и программа даже не запустится. Примером может быть забытая `;`, неправильно расставленные скобки и другие детали.
+## Что такое синтаксическая ошибка?
 
-Вот пример кода с синтаксической ошибкой:
+Синтаксическая ошибка (SyntaxError) — это нарушение грамматических правил языка программирования. Такие ошибки возникают, если код написан с отклонением от ожидаемого формата: не закрыта строка, пропущена скобка, нарушен порядок символов и т.д.
+
+В отличие от естественных языков, где текст с ошибками можно понять по контексту, в программировании правила строги: даже малейшее отклонение делает код неработоспособным.
+
+Рассмотрим простой пример:
 
 ```python
 print('Hodor)
 ```
 
-https://replit.com/@hexlet/python-basics-syntax-errors
-
-Если запустить код выше, то мы увидим следующее сообщение:
+В этом коде не закрыта кавычка, и Python не может завершить строку. Попробуем запустить программу:
 
 ```bash
 $ python index.py
@@ -21,4 +26,23 @@ File "index.py", line 1
 SyntaxError: EOL while scanning string literal
 ```
 
-С одной стороны, ошибки синтаксиса — самые простые, потому что они связаны с грамматическими правилами написания кода, а не со смыслом кода. Их легко исправить: нужно лишь найти нарушение в записи. С другой стороны, интерпретатор не всегда может четко указать на это нарушение. Поэтому бывает, что забытую скобку нужно поставить не туда, куда указывает сообщение об ошибке.
+Интерпретатор сообщает, что строка закончилась, но строковый литерал не завершён — EOL while scanning string literal.
+
+## Почему такие ошибки считаются простыми?
+
+Синтаксические ошибки:
+
+- легко заметить — код часто подсвечивается в редакторе;
+- легко исправить — достаточно вернуть пропущенный символ или поправить структуру.
+
+Но есть и нюансы:
+
+🧠 Интерпретатор не всегда указывает точно то место, где допущена ошибка.
+Иногда проблема находится несколькими строками выше. Например, открытая, но не закрытая скобка на одной строке может «сломать» весь следующий код.
+
+## Что делать при синтаксической ошибке?
+
+- Читай сообщение об ошибке. Оно почти всегда содержит полезную информацию.
+- Проверь строку, указанную в сообщении.
+- Проверь строку до неё. Иногда ошибка «спрятана» чуть раньше.
+- Используй редактор с подсветкой синтаксиса — он поможет сразу заметить проблемы (например, незакрытые кавычки или скобки).