feat(10-basics): полный перенос теории из Python и адаптация под java

checkstyle.xml

@@ -171,7 +171,8 @@
     <!-- See https://checkstyle.org/config_misc.html -->
     <module name="ArrayTypeStyle"/>
     <!-- <module name="FinalParameters"/> -->
-    <module name="TodoComment"/>
+    <!-- TodoComment отключён: в курсе есть уроки, где TODO-комментарии — часть задания -->
+    <!-- <module name="TodoComment"/> -->
     <module name="UpperEll"/>
 
     <!-- https://checkstyle.org/config_filters.html#SuppressionXpathFilter -->

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

@@ -14,7 +14,15 @@ class App {
 }
 ```
 
-Текст *Hello, World!* появится на экране благодаря команде `System.out.println()`, где `println()` — это сокращение от английского *print line*. Она выводит на экран значение, указанное в скобках `("Hello, World!")` — в данном случае строку. Сама строка обрамляется двойными кавычками `""`. Если этого не сделать, то компилятор укажет на синтаксическую ошибку:
+Текст *Hello, World!* появится на экране благодаря команде `System.out.println()`, где `println()` — это сокращение от английского *print line*. Она выводит на экран значение, указанное в скобках `("Hello, World!")` — в данном случае строку. Вместо примера можно вывести любой другой текст:
+
+```java
+System.out.println("Хекслет — школа программирования");
+```
+
+Команда остаётся той же, меняется только содержимое скобок.
+
+Чтобы программа понимала, что в скобках именно текст, его заключают в кавычки. В Java строка всегда обрамляется **двойными** кавычками `"..."`. Одинарные кавычки `'...'` для строки использовать нельзя: в них записывают одиночный символ (тип `char`), например `'A'`. Если обрамить строку одинарными кавычками, компилятор укажет на синтаксическую ошибку:
 
 ```bash
 # Например, вот так
@@ -27,14 +35,36 @@ System.out.println('Hello, World!');
 
 Сейчас мы не будем на них останавливаться, так как для их понимания нужно уметь немного программировать. Поэтому во многих заданиях они даются «как есть», то есть вам не придется их задавать самостоятельно. Когда придет время, мы их разберем.
 
-## JShell
+## Значение символов
+
+Код состоит из команд, и каждая из них должна быть написана в определённой форме. Помимо букв, в коде важны кавычки `"`, скобки `()`, фигурные скобки `{}` и точка с запятой `;`. Пропущенный или перепутанный знак приведёт к тому, что программа не скомпилируется. Попробуйте определить, какая ошибка допущена в каждой из строк?
+
+```java
+System.out.println("I am the King");
+System.out.println("I am the King";
+System.out.println(I am the King");
+System.ouprintln("I am the King");
+System.out.println("I am the King")
+```
 
-Двигаясь по урокам, вы постоянно будете встречаться с примерами кода и описаниями его работы. Чтобы их лучше понимать и уметь пользоваться языком, нужно постоянно практиковаться и экспериментировать.
+Даже небольшое отличие — лишняя буква, потерянная скобка или забытая `;` — может привести к тому, что программа не заработает. Это относится и к регистру, то есть к различию между большими и маленькими буквами. Если в обычном тексте `Привет` и `привет` выглядят одинаково, то для Java это разные слова. Java считает `println`, `Println` и `PRINTLN` разными именами, и сработает только первый вариант.
 
-Поэтому по возможности запускайте все примеры из теории и проводите эксперименты с непонятными моментами.
+## Где практиковаться
 
-С Java проще всего начать на сайте [onecompiler](https://onecompiler.com/jshell), который позволяет запускать построчно код прямо в браузере. Попробуйте перейти туда прямо сейчас и набрать такой код:
+Теория усваивается лучше, когда параллельно запускаешь код и видишь результат. Двигаясь по урокам, вы постоянно будете встречаться с примерами кода и описаниями его работы. Чтобы лучше их понимать и уметь пользоваться языком, нужно постоянно практиковаться и экспериментировать — по возможности запускайте все примеры из теории.
+
+С Java проще всего начать на сайте [onecompiler](https://onecompiler.com/jshell), который позволяет запускать код построчно прямо в браузере с помощью JShell. Попробуйте перейти туда прямо сейчас и набрать такой код:
 
 ```text
 System.out.println(85 * 3);
 ```
+
+Как это работает технически? В отличие от языков, которые выполняются построчно интерпретатором, код на Java сначала проходит через компилятор, а затем выполняется виртуальной машиной Java (JVM), которая и выводит на экран результат:
+
+```text
+Код                      Компилятор + JVM           Экран
+┌──────────────────┐     ┌─────────────────┐     ┌──────────────┐
+│ System.out       │ ──→ │  javac + JVM    │ ──→ │ Hello, World!│
+│   .println(…)    │     │                 │     │              │
+└──────────────────┘     └─────────────────┘     └──────────────┘
+```

modules/10-basics/20-comments/App.java

@@ -1,7 +1,7 @@
 class App {
     public static void main(String[] args) {
         // BEGIN
-        // You know nothing, Jon Snow!
+        // TODO: добавить метод приветствия
         // END
     }
 }

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

@@ -1,5 +1,9 @@
-Создайте однострочный комментарий с текстом:
+Вы пишете программу и понимаете, что одну часть нужно доделать позже. Чтобы не забыть, программисты оставляют себе заметки прямо в коде — TODO-комментарии.
+
+Добавьте в файл такой однострочный комментарий:
 
 ```text
-You know nothing, Jon Snow!
+// TODO: добавить метод приветствия
 ```
+
+Когда вернётесь к этому месту позже, комментарий напомнит, что здесь ещё есть незавершённая работа.

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

@@ -1,4 +1,17 @@
-Практически все языки программирования позволяют оставлять в коде комментарии. Они никак не используются кодом и нужны исключительно для людей: чтобы программист оставлял пометки для себя и для других программистов.
+Практически все языки программирования позволяют оставлять в коде комментарии. Они никак не используются кодом и нужны исключительно для людей: чтобы программист оставлял пометки для себя и для других программистов, пояснял, как работает код, отмечал ошибки или напоминал, что нужно доделать.
+
+```java
+// Удалить строку ниже после реализации задачи по регистрации
+System.out.println(10);
+```
+
+Компилятор полностью игнорирует комментарии — на работу программы они не влияют:
+
+```text
+// комментарий                       ──→  [ пропущено компилятором ]
+System.out.println("hello");         ──→  [ выполнено → hello ]
+// ещё один                          ──→  [ пропущено компилятором ]
+```
 
 Комментарии в Java бывают трех видов:
 
@@ -29,3 +42,23 @@ System.out.println("I am the King"); // => I am the King
 **Документирующие комментарии** начинаются с `/**` и заканчиваются на `*/`. Уже для них обязательно каждую строку начинать с символа `*`.
 
 Документирующие комментарии — это подвид многострочных. При этом несут дополнительную функцию — их можно собрать при помощи специальной утилиты javadoc и выдать в качестве документации к вашему коду. Мы поговорим о них позже – когда разберем классы и методы.
+
+## Служебные комментарии
+
+В процессе работы вы будете встречаться с таким кодом в нашем редакторе:
+
+```java
+// BEGIN
+
+// END
+```
+
+*BEGIN* и *END* здесь — это обычные однострочные комментарии, которые никак не влияют на работу программы. Они показывают, куда писать код задания.
+
+```java
+// BEGIN
+<здесь ваше решение>
+// END
+```
+
+Увидев *BEGIN* и *END*, пишите свой код между ними, остальное оставляйте без изменений.

modules/10-basics/20-comments/ru/data.yml

@@ -1,2 +1,11 @@
 ---
 name: Комментарии
+tips:
+  - >
+    [Подробнее о
+    комментариях](https://www.w3schools.com/java/java_comments.asp)
+definitions:
+  - name: Комментарий
+    description: >
+      текст в коде программы, который не влияет на функциональность и
+      добавляется программистами для себя и своих коллег.

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

@@ -1,8 +1,18 @@
-Инструкция — это команда для компьютера. Код на Java — это набор инструкций, которые, обычно, отделяются друг от друга символом `;`. Вот пример кода с двумя инструкциями:
+Инструкция — это команда для компьютера. Код на Java — это набор инструкций, и каждая из них завершается символом `;`. Таких инструкций может быть сколько угодно: каждая выполняется после того, как закончилась предыдущая, и так из простых элементов получается сколь угодно большая и сложная программа.
+
+```text
+Инструкция 1: System.out.println("Hello");   →  выполнена
+        ↓
+Инструкция 2: System.out.println("World");   →  выполнена
+        ↓
+Инструкция 3: System.out.println("!");        →  выполнена
+```
+
+Вот пример кода с двумя инструкциями. Эти строки говорят компьютеру вывести фразы на экран:
 
 ```java
-System.out.println("Mother of Dragons");
-System.out.println("Dracarys!");
+System.out.println("Mother of Dragons"); // Первая инструкция
+System.out.println("Dracarys!"); // Вторая инструкция
 ```
 
 При запуске этого кода на экран последовательно выводятся два предложения:
@@ -12,12 +22,52 @@ Mother of Dragons
 Dracarys!
 ```
 
-Почему это важно знать? Инструкция — это единица исполнения. Программа, которая запускает код на Java, выполняет инструкции строго по очереди. Разработчики должны понимать этот порядок и уметь мысленно разделять программу на независимые части, удобные для анализа.
+## Порядок имеет значение
+
+Java выполняет код строго в том порядке, в котором вы его написали. Если поменять строки местами:
+
+```java
+System.out.println("Dracarys!");
+System.out.println("Mother of Dragons");
+```
+
+на экране они тоже поменяются:
+
+```text
+Dracarys!
+Mother of Dragons
+```
+
+## Завершение инструкций
 
-Теоретически инструкции можно написать последовательно друг за другом без переноса на новую строчку:
+В Java символ `;` обязателен — он отмечает конец каждой инструкции. Если его забыть, компилятор сообщит об ошибке. Благодаря `;` несколько инструкций можно даже записать на одной строке:
 
 ```java
-System.out.println("Mother of Dragons."); System.out.println("Dracarys!");
+System.out.println("Mother of Dragons"); System.out.println("Dracarys!");
 ```
 
-Результат на экране будет таким же, но на практике такой подход считается плохим.
+Результат на экране будет таким же, но на практике такой подход считается плохим: код труднее читать. Поэтому инструкции почти всегда пишут по одной на строку.
+
+## Зачем это нужно
+
+Сейчас мы пишем очень простые программы, но со временем они начнут усложняться. Один из самых важных навыков, который поможет их понимать, — это способность мысленно разбивать программу на независимые инструкции. Только так можно разобраться, что в коде происходит. Ниже пример для привлечения внимания, понимать его пока не надо:
+
+```java
+static boolean isPrime(int number) {
+    if (number < 2) {
+        return false;
+    }
+
+    int divider = 2;
+
+    while (divider <= number / 2) {
+        if (number % divider == 0) {
+            return false;
+        }
+
+        divider++;
+    }
+
+    return true;
+}
+```

modules/10-basics/30-statements/ru/data.yml

@@ -1,2 +1,14 @@
 ---
 name: Инструкции (Statements)
+tips:
+  - |
+    [Что такое компилятор?](https://guides.hexlet.io/compiler/)
+definitions:
+  - name: Компилятор
+    description: >-
+      программа, преобразующая исходный код на Java в формат, который
+      выполняет виртуальная машина Java (JVM).
+  - name: Инструкция (statement)
+    description: >-
+      команда для компьютера, написанная на языке программирования. Код на
+      Java — это набор инструкций, каждая из которых завершается символом `;`.

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

@@ -14,7 +14,9 @@ expected: "35" but was: "10"
 
 Самое главное начинается после двоеточия: «ожидалось: "35", но было "10"». То есть правильный код должен был выдать 35, но текущее решение работает неправильно и выдаёт 10.
 
----
+Такой подход называется тестированием, и он используется в реальной разработке. Тесты помогают проверить, правильно ли работает программа, и быстро заметить ошибку после изменений. Именно поэтому наш сайт говорит «Тесты пройдены», когда вы правильно решили задачу.
+
+## Моя ошибка или нет?
 
 Иногда в процессе решения будет казаться, что вы сделали все правильно, но система "капризничает" и не принимает решение. Подобное поведение практически исключено. Нерабочие тесты просто не могут попасть на сайт, они автоматически запускаются после каждого изменения. В подавляющем большинстве таких случаев, (а все наши проекты в сумме провели миллионы проверок за много лет), ошибка содержится в коде решения. Она может быть очень незаметной, вместо английской буквы случайно ввели русскую, вместо верхнего регистра использовали нижний или забыли вывести запятую. Другие случаи сложнее. Возможно ваше решение работает для одного набора входных данных, но не работает для другого. Поэтому всегда внимательно читайте условие задачи и вывод тестов. Там почти наверняка есть указание на ошибку.