feat(40-methods-definition): перенос теории из Python и адаптация под java

modules/40-methods-definition/100-method-definition-static/ru/README.md

@@ -1,6 +1,6 @@
 Определение собственных методов значительно упрощает написание и поддержку программ. Например, методы позволяют объединять составные операции в одну.
 
-К примеру, отправка письма на сайте — это достаточно сложный процесс, включающий в себя взаимодействие с интернетом. Можно определить метод и скрыть всю сложность за одной простой конструкцией:
+К примеру, отправка письма на сайте — это сложный процесс, включающий в себя взаимодействие с интернетом. Можно определить метод и скрыть всю сложность за одной короткой конструкцией:
 
 ```java
 // Место откуда берется метод
@@ -45,6 +45,17 @@ public class App {
 App.showCurrentDate(); // => Today is: 2021-10-25
 ```
 
+Посмотрим на сигнатуру метода по частям:
+
+```text
+public static void showCurrentDate()
+  │      │     │           │
+  │      │     │           имя метода и список параметров в скобках
+  │      │     тип возвращаемого значения
+  │      static — метод вызывается напрямую из класса
+  видимость метода снаружи класса
+```
+
 Определение метода в Java включает в себя много действий, которые мы постепенно разберем.
 
 Их можно разделить на две группы:
@@ -59,7 +70,7 @@ App.showCurrentDate(); // => Today is: 2021-10-25
 * *static* — отвязывает метод от объекта и делает возможным его вызов напрямую из класса
 * *void* используется, если метод ничего не возвращает. Например, такое определение у метода `System.out.println()`. Если метод возвращает какие-то данные, то вместо *void* указывается тип возвращаемых данных
 
-В отличие от обычных данных, методы выполняют действия, поэтому их имена практически всегда должны быть глаголами: «построить что-то», «нарисовать что-то», «открыть что-то».
+В отличие от обычных данных, методы выполняют действия, поэтому их имена практически всегда должны быть глаголами: "построить что-то", "нарисовать что-то", "открыть что-то".
 
 Все, что описывается внутри фигурных скобок `{}`, называется **телом метода**. Внутри тела можно описывать любой код. Считайте, что это маленькая самостоятельная программа, набор произвольных инструкций.
 
@@ -77,4 +88,18 @@ public class App {
 App.noop();
 ```
 
-Понятие «создать метод» имеет много синонимов: «реализовать», «определить» и даже «заимплементить». Все эти термины встречаются в повседневной практике на работе.
+Понятие "создать метод" имеет много синонимов: "реализовать", "определить" и даже "заимплементить". Все эти термины встречаются в повседневной практике на работе.
+
+## Переиспользование и читаемость
+
+Методы помогают избегать дублирования. Допустим, в программе несколько раз встречается один и тот же набор действий:
+
+```java
+System.out.println("Hello, Hexlet!");
+System.out.println("Hello, world!");
+System.out.println("Hello, Java!");
+```
+
+Такой шаблон можно собрать в один метод и вызывать его в разных местах. Когда понадобится поменять текст, правка вносится в одном месте — в определении метода. Чем больше проект и чем чаще повторяется логика, тем заметнее выигрыш.
+
+Название метода само по себе подсказывает, что он делает. Метод `showCurrentDate()` говорит о своей задаче без дополнительных комментариев. Это помогает другим программистам читать код, а заодно и вам самим через месяц после написания.

modules/40-methods-definition/200-method-definition-return/ru/data.yml

@@ -1,2 +1,5 @@
 ---
 name: Возврат значений
+tips:
+  - |
+    [Оператор return в Java](https://www.w3schools.com/java/ref_keyword_return.asp)

modules/40-methods-definition/300-method-definition-parameters/ru/README.md

@@ -84,26 +84,27 @@ App.average(1, 2); // 1.5
 ```java
 // первый параметр – что ищем
 // второй параметр – на что меняем
-'google'.replace('go', 'mo'); // moogle
-````
+"google".replace("go", "mo"); // "moogle"
+```
 
-Для создания таких методов, нужно в определении указать нужное количество параметров через запятую, дав им понятные имена. Ниже пример определения метода `replace()`, который заменяет в слове одну часть строки на другую:
+Для создания таких методов нужно в определении указать нужное количество параметров через запятую, дав им понятные имена. Ниже пример определения метода `replace()`, который заменяет в слове одну часть строки на другую:
 
 ```java
 class App {
     public static String replace(String text, String from, String to) {
-        // здесь тело метода, но мы его
+        // Здесь тело метода, но мы его
         // опускаем, чтобы не отвлекаться
+        return text.replace(from, to);
     }
 }
 
-App.replace('google', 'go', 'mo'); // moogle
+App.replace("google", "go", "mo"); // "moogle"
 ```
 
-Когда параметров два и более, то практически для всех методов становится важен порядок передачи этих параметров. Если его поменять, то метод отработает по-другому:
+Когда параметров два и более, то практически для всех методов становится важен порядок передачи этих параметров. От перестановки аргументов местами результат метода меняется:
 
 ```java
-// ничего не заменилось,
+// Ничего не заменилось,
 // так как внутри google нет mo
-App.replace('google', 'mo', 'go'); // google
+App.replace("google", "mo", "go"); // "google"
 ```

modules/40-methods-definition/400-method-definition-default-parameters/ru/README.md

@@ -1,62 +1,44 @@
-<!-- возможно стоит добавить перед этим уроком урок про перегрузку методов -->
+В программировании у многих методов есть параметры, которые редко меняются. Часто такому параметру удобно задать одно значение и подставлять его, когда при вызове ничего другого не передали. Такое значение называют **значением по умолчанию**.
 
-В программировании большое количество функций и методов имеют параметры, которые редко меняются.
+Во многих языках значение по умолчанию пишут прямо в определении. Например, в Python метод возведения в степень выглядит так:
 
-В таких случаях этим параметрам задают **значения по умолчанию**, которые можно поменять по необходимости. Этим немного сокращается количество одинакового кода.
+```python
+# Степень — это второй параметр со значением по умолчанию 2
+def pow(x, base=2):
+    return x ** base
 
-Это наглядно видно на таком примере:
-
-```javascript
-// Пример того, как задаются параметры по умолчанию в языке JavaScript
-class App {
-    // Функция возведения в степень
-    // Степень — это второй параметр со значением по умолчанию 2
-    function pow(x, base = 2) {
-      return x ** base;
-    }
-}
-
-App.pow(3); // Результат — 9, так как по умолчанию возводим во вторую степень
-// Возводим в третью степень
-App.pow(3, 3); // 27
+pow(3)     # 9, по умолчанию возводим во вторую степень
+pow(3, 3)  # 27, степень передана явно
 ```
 
-В отличие от других языков, в Java нет возможности задать значение по умолчанию, но ее можно имитировать с помощью **перегрузки методов**.
+В Java у параметров нет значений по умолчанию. Зато тот же результат достигается через **перегрузку методов**.
 
 Что это такое? Java позволяет создать несколько методов с одинаковым именем. У таких одинаковых методов должны быть:
 
 * Разные типы входных параметров
 * Разное количество параметров
 * Или все это одновременно
 
-Посмотрим на примере метода, складывающего два числа:
+Посмотрим на примере метода, складывающего числа. Создадим две версии `sum()` в одном классе. Первая принимает два числа, вторая принимает только одно и прибавляет к нему 10:
 
 ```java
 class App {
     public static int sum(int x, int y) {
         return x + y;
     }
-}
 
-App.sum(2, 3); // 5
-```
-
-Теперь напишем другой метод `sum()`, который принимает только один параметр и складывает его с числом 10:
-
-```java
-class App {
     public static int sum(int x) {
         return x + 10;
     }
 }
 
-App.sum(2); // 12
-App.sum(2, 1); // 3
+App.sum(2, 3); // 5, сработала версия с двумя параметрами
+App.sum(2);    // 12, сработала версия с одним параметром
 ```
 
-Компилятор без проблем выполнит такой код и создаст два метода с одним именем. Как Java узнает, какой метод нужно использовать?
+Компилятор без проблем создаст два метода с одним именем. Как Java узнает, какой из них вызвать?
 
-Все очень просто: во время компиляции выбирается та версия метода, которая совпадает по типу и количеству параметров. Если такой метод не был найден, то возникнет ошибка.
+Во время компиляции выбирается та версия метода, которая совпадает по типу и количеству параметров. Когда подходящего метода нет, компилятор сообщает об ошибке.
 
 Как минимум с одним перегруженным методом мы уже встречались — это метод `substring()`. По умолчанию он извлекает подстроку до конца, но ему можно передать второй параметр, который ограничит длину: