p.strelchenko
1030 lines
54 KiB
Markdown
1030 lines
54 KiB
Markdown
# Код-стайл оформления кода уроков
|
||
|
||
Этот документ содержит в себе описание согласованного код-стайла для оформления текстов уроков Яндекс.Практикума.
|
||
|
||
## Структура репозитория
|
||
|
||
В общем виде структура репозитория выглядит так:
|
||
|
||
```yaml
|
||
- .github # Описание CI/CD pipeline на основе `GitHub Actions` и базовые шаблоны для GitHub.
|
||
- .idea # Папка с настройкой IntelliJ IDEA для работы в репозитории.
|
||
- docs # Документация проекта.
|
||
- projects # Дополнительные утилиты для поддержки проекта.
|
||
|
||
# Папки с текстами уроков
|
||
- 01. Спринт:
|
||
- 01. История Java:
|
||
- assets:
|
||
- gif:
|
||
- animated_scheme.gif
|
||
- img:
|
||
- screenshot_01.png
|
||
- scheme_01.png
|
||
- picture:
|
||
- java_island.png
|
||
- rough_language_1.png
|
||
- rough_language_2.png
|
||
- raw:
|
||
- screenshot_01__raw.png
|
||
- scheme_01__raw.png
|
||
- video:
|
||
- screen_recording.mp4
|
||
- code:
|
||
- snippets:
|
||
- snippet_fix_numbers.md
|
||
- snippet_add_letters.md
|
||
- trainers:
|
||
- trainer_piggy_bank.md
|
||
- 01. Java. Предпосылки.md
|
||
- 02. Составляющие инфраструктуры Java.md
|
||
- 03. Как Android встретила Java.md
|
||
- 02. Классы и объекты
|
||
- 02.Sprint
|
||
- ...
|
||
- ...
|
||
- Diploma
|
||
```
|
||
|
||
### Содержимое папок с уроками
|
||
|
||
1. Каждому спринту курса соответствует отдельная папка в корне проекта (например: `01.Sprint`, `02.Sprint`, etc). Цифра
|
||
обозначает номер спринта.
|
||
|
||
```yaml
|
||
- 01. Спринт
|
||
- 02. Спринт
|
||
- ...
|
||
```
|
||
|
||
2. Каждой теме соответствует отдельная папка внутри папки
|
||
спринта (например: `02.Sprint/01. Методы/`, `02.Spring/02. Классы и объекты`, etc). Цифра возле названия темы
|
||
соответствует порядковому номеру темы внутри спринта.
|
||
|
||
```yaml
|
||
- 01. Спринт:
|
||
- 01. Начало платного обучения
|
||
- 02. История Java
|
||
- 03. Объявление переменных
|
||
- ...
|
||
- 02. Спринт:
|
||
- 01. Методы
|
||
- 02. Классы и объекты
|
||
- 03. Git для самых маленьких
|
||
- ...
|
||
- ...
|
||
```
|
||
|
||
3. Каждому уроку внутри темы соответствует отдельный MD-файл с названием урока (
|
||
например: `03.Sprint/01. Массивы, списки, итераторы/01. Массивы.md`). Цифра возле названия урока соответствует
|
||
порядковому номеру урока внутри темы спринта.
|
||
|
||
```yaml
|
||
- 01. Спринт:
|
||
- 01. Начало платного обучения:
|
||
- 01. Снова здравствуйте!.md
|
||
- 02. Начало спринта № 1.md
|
||
- 02. История Java:
|
||
- 01. Java. Предпосылки.md
|
||
- 02. Составляющие инфраструктуры Java.md
|
||
- 03. Как Android встретила Java.md
|
||
- 03. Объявление переменных:
|
||
- ...
|
||
- ...
|
||
```
|
||
|
||
4. Внутри папки с темой может находиться папка `assets`, предназначенная для хранения всех дополнительных ресурсов,
|
||
связанных с конкретной темой. К ресурсам относятся: скриншоты, схемы, картинки от иллюстратора, видео, гиф-анимации и
|
||
исходники изображений.
|
||
|
||
```yaml
|
||
- 01.Sprint:
|
||
- 01. Начало платного обучения:
|
||
- assets:
|
||
- gif:
|
||
- animated_scheme.gif
|
||
- img:
|
||
- screenshot_01.png
|
||
- scheme_01.png
|
||
- picture:
|
||
- java_island.png
|
||
- rough_language_1.png
|
||
- rough_language_2.png
|
||
- raw:
|
||
- screenshot_01__raw.png
|
||
- scheme_01__raw.png
|
||
- video:
|
||
- screen_recording.mp4
|
||
- code:
|
||
- ...
|
||
- 01. Снова здравствуйте!.md
|
||
- 02. Начало спринта № 1.md
|
||
- ...
|
||
- ...
|
||
```
|
||
|
||
- В папке `gif` должны находиться GIF-анимации.
|
||
- В папке `img` находятся обработанные скриншоты и перерисованные схемы.
|
||
- В папке `picture` должны лежать изображения от иллюстратора.
|
||
- В папке `video` - видео.
|
||
- В папке `raw` должны находиться исходники скриншотов и исходники схем, которым требуется перерисовка.
|
||
|
||
5. Внутри папки с темой может находиться папка `code`, предназначенная для хранения кода тренажёров (`trainers`)
|
||
и сниппетов (`snippets`), связанных с конкретной темой. Название файла должно быть осмысленным и
|
||
иметь префикс `snippet` или `trainer`.
|
||
|
||
```yaml
|
||
- 01.Sprint:
|
||
- 01. Начало платного обучения:
|
||
- assets:
|
||
- ...
|
||
- code:
|
||
- snippets:
|
||
- snippet_fix_numbers.md
|
||
- snippet_add_letters.md
|
||
- trainers:
|
||
- trainer_piggy_bank.md
|
||
- 01. Снова здравствуйте!.md
|
||
- 02. Начало спринта № 1.md
|
||
- ...
|
||
- ...
|
||
```
|
||
|
||
## Договорённости по названиям и форматам файлов
|
||
|
||
- Названия любых файлов не должны иметь специальных символов кроме точки (`.`), нижнего подчёркивания (`_`),
|
||
восклицательного знака (`!`), дефиса (`-`), вопросительного знака (`?`).
|
||
- Папки спринтов имеют формат `01. Спринт`, `02. Спринт` - порядковый номер, точка, пробел и слово `Спринт`.
|
||
- Папки с темами имеют формат `01. Название темы`, `02. Название второй темы` - порядковый номер, точка, пробел и
|
||
название темы.
|
||
- Файлы с текстами уроков имеют формат `01. Название урока.md`, `02. Название второго урока.md` - порядковый номер,
|
||
точка, пробел и название урока. Файл с текстом урока имеет расширение `.md`.
|
||
- Каждый файл, относящийся к тексту уроков, должен иметь понятные и осмысленные названия:
|
||
- Файл с текстом очередного урока должен иметь такое же название, как и заголовок уровня `H1` на странице Платформы.
|
||
- Файлы с изображениями должны называться понятно для всех участников процесса разработки:
|
||
- вместо сокращений используем полные слова;
|
||
- желательно использовать не транслит, а корректные английские фразы;
|
||
- если название состоит из нескольких слов, соединяем их с помощью знака нижнего подчёркивания (`_`);
|
||
- если есть несколько изображений, относящихся к одному и тому же блоку, но их нужно различать, разрешается
|
||
сделать общий префикс, и отделить его от основного описания файла двумя символами нижнего
|
||
подчёркивания (`__`).
|
||
- избегайте большого числа специальных символов в названии файла, желательно иметь только одну точку (`.`) в
|
||
названии файла.
|
||
|
||
**DO:**
|
||
|
||
- `android_studio__git_history.png`;
|
||
- `gmail_split_screen.png`;
|
||
- `image_gallery_block.png`.
|
||
|
||
**DON'T:**
|
||
|
||
- `skrinshot.png`;
|
||
- `ndr.png`;
|
||
- `some_schema.excalidraw.png`;
|
||
- `02skrin_Find_json_to_kotlin_03.png`.
|
||
|
||
## Оформление текста
|
||
|
||
### Общее
|
||
|
||
- В одной строке может быть максимум 120 символов.
|
||
- Если текст, обрамлённый специальными символами, не помещается в размеры стандартной строчки, нужно перенести его на
|
||
следующую строчку, чтобы при автоматическом форматировании файла IDE не портила оформление текста.
|
||
|
||
### Жирный шрифт
|
||
|
||
- Текст, который нужно выделить **жирным** шрифтом, выделяется двумя символами-звёздочками (`*`) с двух сторон:
|
||
|
||
```markdown
|
||
Когда мы смотрим на макет, нам нужно понимать, как отдельные элементы интерфейса (баннеры, кнопки, иконки) расположены
|
||
**друг относительно друга**.
|
||
```
|
||
|
||
### Код внутри строки
|
||
|
||
- Текст, который нужно выделить как `код`, выделяется одинарными косыми кавычками (\`текст\`):
|
||
|
||
```markdown
|
||
В документации вы можете увидеть требование передавать в запросах заголовок `User-Agent`. Этот заголовок может содержать
|
||
информацию о типе устройства, операционной системе, используемой версии приложения и другие детали. Получается что-то
|
||
вроде визитной карточки вашего устройства.
|
||
```
|
||
|
||
### Блоки кода
|
||
|
||
- Блоки кода начинаются тройным повторением одинарной косой кавычки (\`) и обязательным указанием **языка** для этого
|
||
блока. Код внутри блока должен соответствовать стандартам языка программирования. Блок заканчивается тройным
|
||
повторением одинарной косой кавычки.
|
||
|
||
```xml
|
||
<?xml version="1.0" encoding="utf-8"?>
|
||
<androidx.coordinatorlayout.widget.CoordinatorLayout
|
||
xmlns:android="http://schemas.android.com/apk/res/android"
|
||
xmlns:app="http://schemas.android.com/apk/res-auto"
|
||
android:layout_width="match_parent"
|
||
android:layout_height="match_parent">
|
||
|
||
<TextView
|
||
android:id="@+id/name"
|
||
android:layout_width="match_parent"
|
||
android:layout_height="wrap_content"
|
||
android:layout_marginHorizontal="40dp"
|
||
android:layout_marginTop="40dp"
|
||
android:text="Детали фильма"
|
||
android:textColor="@color/white"
|
||
android:textSize="18sp"
|
||
app:layout_constraintTop_toTopOf="parent" />
|
||
|
||
</androidx.coordinatorlayout.widget.CoordinatorLayout>
|
||
```
|
||
|
||
- В качестве блока кода также можно указывать выводы из консоли. В этом случае указание языка должно отсутствовать.
|
||
|
||
```
|
||
D New value: 1
|
||
D New value: 2
|
||
D New value: 3
|
||
D New value: 4
|
||
D New value: 5
|
||
D New value: 6
|
||
```
|
||
|
||
#### Стандарты языков программирования
|
||
|
||
- [Code conventions JAVA](https://www.oracle.com/technetwork/java/codeconventions-150003.pdf)
|
||
- [Code conventions KOTLIN](https://kotlinlang.org/docs/coding-conventions.html)
|
||
- [Swift Style Guide](https://google.github.io/swift/)
|
||
|
||
## Изображения, видео, gif
|
||
|
||
### Общее
|
||
|
||
- Разрешённые расширения файлов: `.png`, `.gif` и `.mp4`.
|
||
- Файлы-исходники, которые находятся в папке `raw`, должны иметь в названии суффикс `__raw`. После того как исходник
|
||
будет обработан и положен в папку `img`, название нового изображения должно совпадать с именем исходника за
|
||
исключением суффикса `__raw`.
|
||
- Скриншоты Android Studio делаются в **Dark**-теме (в старом UI - тема `Darcula`).
|
||
- Скриншоты Github
|
||
делаются [в тёмной теме](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-your-theme-settings).
|
||
- Изображения, связанные с Android Studio (скриншоты выбора проекта, скриншоты, связанные с отображением кода, etc),
|
||
должны быть отмечены в [специальном перечне](../android_studio_screenshots.md).
|
||
|
||
**DO:**
|
||
|
||
- `01_splash_screen.png`.
|
||
- `Skrinshot_09.png`.
|
||
- `here_we_go_again.png`.
|
||
|
||
**DON'T:**
|
||
|
||
- `всё очень плохо.png`.
|
||
- `скрин 1.png`.
|
||
|
||
### Код-стайл
|
||
|
||
- Блок с картинкой или видео начинается строкой `**КАРТИНКА**` (или `**ВИДЕО**`), затем идёт пустая строка, а потом
|
||
описывается относительный путь до картинки внутри репозитория.
|
||
|
||
```markdown
|
||
**КАРТИНКА**
|
||
|
||
|
||
|
||
**ВИДЕО**
|
||
|
||
|
||
```
|
||
|
||
- Если картинка или видео взяты с платформы посредством выполнения скрипта актуализации, блок с начинается
|
||
строкой `**КАРТИНКА (ВЗЯТО С ПЛАТФОРМЫ)**` или `**ВИДЕО (ВЗЯТО С ПЛАТФОРМЫ)**`, затем идёт пустая строка, а потом
|
||
описывается ссылка на картинку.
|
||
|
||
```markdown
|
||
**КАРТИНКА (ВЗЯТО С ПЛАТФОРМЫ)**
|
||
|
||
|
||
|
||
**ВИДЕО (ВЗЯТО С ПЛАТФОРМЫ)**
|
||
|
||
|
||
```
|
||
|
||
- Техническое задание для иллюстратора начинается упоминанием Github-ника иллюстратора, затем идёт описание задания.
|
||
|
||
```markdown
|
||
@sashasketchit Нарисовать аналог в нашей тематике.
|
||
|
||
@sashasketchit Может тут стоить нарисовать ЭНДИ с испуганным лицом и капельками пота на лице или сидящим за столом с
|
||
водкой и сигаретой (как в том меме).
|
||
```
|
||
|
||
- Каждое изображение в коде должно иметь осмысленный альтернативный текст (Пока что
|
||
на Платформе не описывается альтернативный текст, поэтому в качестве описания картинки после актуализации текста
|
||
пишется просто `image`.).
|
||
|
||
**DO**
|
||
|
||
```markdown
|
||
|
||
|
||
|
||
```
|
||
|
||
**DON'T**
|
||
|
||
```markdown
|
||
|
||
|
||
|
||
```
|
||
|
||
## Особое выделение блоков на Платформе
|
||
|
||
На Платформе есть возможность выделять блоки текста множеством разных способов. Чтобы при переносе контента урока из
|
||
репозитория на Платформу эти блоки не потерялись, нужно корректно выделять их в тексте `Markdown`-файлов.
|
||
|
||
### Термин для глоссария
|
||
|
||
Мы можем выделять термины таким образом, чтобы при наведении на них, мы могли отобразить дополнительные пояснения.
|
||
|
||
На Платформе это выглядит так:
|
||
|
||
|
||
|
||
### Блоки с цитатами
|
||
|
||
Блоки с цитатами предназначены для дополнительного выделения некоторого цитируемого текста, например, в тексте урока
|
||
приводится пример технического задания, или пример рассуждений какого-то человека.
|
||
|
||
На Платформе эти блоки выглядят так:
|
||
|
||
|
||
|
||
В коде урока блок с цитатами начинается строкой `**БЛОК ЦИТАТЫ**`, далее следует текст блока. Каждая строка блока
|
||
начинается с символа закрывающей угловой скобки (`>`). Блок заканчивается строкой `**КОНЕЦ БЛОКА ЦИТАТЫ**`.
|
||
|
||
```markdown
|
||
**БЛОК ЦИТАТЫ**
|
||
|
||
>
|
||
> Вот эта надпись находится сверху от кнопки.
|
||
>
|
||
> Эта картинка расположена слева от заголовка.
|
||
>
|
||
> Три иконки в ряд, а вместе они под основным текстом и по центру экрана.
|
||
|
||
**КОНЕЦ БЛОКА ЦИТАТЫ**
|
||
```
|
||
|
||
### Блок пояснения
|
||
|
||
На Платформе есть возможность выделить блок текста для его большей заметности.
|
||
|
||
На Платформе эти блоки выглядят так:
|
||
|
||
|
||
|
||
|
||
|
||
В коде урока блок пояснения начинается строкой `**БЛОК**`, далее, если хотим добавить заголовок - пишем его текст после
|
||
начальной строки. Затем добавляется пустая строка, после которой начинается описание текста блока. Текст блока может
|
||
содержать только отформатированный текст. Блок заканчивается строкой `**КОНЕЦ БЛОКА**`.
|
||
|
||
```markdown
|
||
**БЛОК**
|
||
|
||
Подсказки для продвинутых задач развёрнутые и направляют к конкретным решениям, поэтому вы вполне можете с ними
|
||
справиться. Если вы придёте к решению самостоятельно, то это уровень специалиста, достойный особого внимания
|
||
работодателей.
|
||
|
||
**КОНЕЦ БЛОКА**
|
||
```
|
||
|
||
Или блок с заголовком:
|
||
|
||
```markdown
|
||
**БЛОК** 💡Совет от разработчика
|
||
|
||
В `RelativeLayout` дочерние элементы по умолчанию привязаны к левому верхнему краю контейнера, как будто бы применены
|
||
атрибуты `layout_alignParentTop="true"` и `layout_alignParentStart="true"`.
|
||
|
||
Мы рекомендуем всегда явно описывать все желаемые атрибуты, чтобы избежать недоразумений.
|
||
|
||
**КОНЕЦ БЛОКА**
|
||
```
|
||
|
||
### Блок-диалог
|
||
|
||
На Платформе есть возможность выразить часть текста как реплики диалога между студентом и роботом Энди. Это полезно,
|
||
когда мы хотим немного разбавить серьёзность урока, добавить какие-то интересные пояснения с короткой подводкой.
|
||
|
||
На Платформе это выглядит так:
|
||
|
||
|
||
|
||
|
||
|
||
В коде урока блок-диалог начинается строкой `**ДИАЛОГ**`. Далее мы указываем реплики в диалоге отдельными строками
|
||
текста. В начале реплики мы указываем "автора" сообщения (если это бот "Энди", то `**ЭНДИ**`, иначе `**СТУДЕНТ**`), а
|
||
дальше отформатированный текст в двойных кавычках (`"`).
|
||
|
||
```markdown
|
||
**ДИАЛОГ**
|
||
|
||
**СТУДЕНТ** "С вертикальными и горизонтальными элементами мы уже работали!"
|
||
**ЭНДИ** "Как растянуть кнопки, тоже знаем!"
|
||
|
||
**КОНЕЦ ДИАЛОГА**
|
||
```
|
||
|
||
- Если же мы хотим добавить одиночную реплику, без диалога, то указываем просто автора реплики, а рядом - текст.
|
||
|
||
```markdown
|
||
**СТУДЕНТ** "Выглядит реализуемо! "
|
||
```
|
||
|
||
- Если мы хотим добавить несколько фраз от одного и того же автора, оформляем это так: начинаем
|
||
строчкой `**МОНОЛОГ ИМЯ_АВТОРА**`, далее идут реплики от лица автора, и заканчиваем строкой `**КОНЕЦ МОНОЛОГА**`.
|
||
|
||
```markdown
|
||
**МОНОЛОГ ЭНДИ**
|
||
|
||
С родительскими контейнерами познакомились!
|
||
А что дальше?
|
||
|
||
**КОНЕЦ МОНОЛОГА**
|
||
```
|
||
|
||
### Блок-реплика
|
||
|
||
На Платформе есть возможность описать кнопку-призыв к действию. Обычно эта кнопка приводит к появлению блока с диалогом.
|
||
|
||
На Платформе это выглядит так:
|
||
|
||
|
||
|
||
В коде урока такая кнопка описывается строкой `**КНОПКА-РЕПЛИКА**`, после чего идёт отформатированный текст.
|
||
|
||
```markdown
|
||
**КНОПКА-РЕПЛИКА** С вертикальными и горизонтальными элементами мы уже работали!
|
||
```
|
||
|
||
### Блок-переход на следующий урок
|
||
|
||
На Платформе есть возможность описать кнопку для перехода на следующий урок. Это может быть как простая фраза, так и
|
||
одно слово.
|
||
|
||
На Платформе это выглядит так:
|
||
|
||
|
||
|
||
В коде урока такая кнопка описывается строкой `**КНОПКА-ПЕРЕХОД**`, после чего идёт отформатированный текст.
|
||
|
||
```markdown
|
||
**КНОПКА-ПЕРЕХОД** Вперёд!
|
||
```
|
||
|
||
### Блок для скрытия/показа контента
|
||
|
||
На Платформе есть возможность оборачивать контент в блоки с возможностью скрытия/показа контента. Это бывает полезно,
|
||
когда мы хотим дать какую-то опциональную теорию или же описать блок, содержимое которого не должно быть сразу видно (
|
||
пример: критерии дипломного проекта с подсказками декомпозиции).
|
||
|
||
На Платформе эти блоки выглядят так:
|
||
|
||
|
||
|
||
|
||
|
||
В коде урока блок для скрытия/показа контента начинается строкой `**СПРЯТАТЬ ПОД КАТ**`, на этой же строке указываем
|
||
заголовок блока, который будет виден пользователю до разворачивания блока. Далее следует текст скрытого блока. Текст
|
||
блока может содержать картинки, списки, блоки с кодом и т.д. Блок заканчивается строкой `**КОНЕЦ КАТА**`.
|
||
|
||
```markdown
|
||
**СПРЯТАТЬ ПОД КАТ** Основная логика приложения и UI
|
||
|
||
Структура вашего будущего приложения похожа на структуру знакомых Playlist Maker и приложения для поиска фильмов. Общий
|
||
набор инструментов, которые вам предстоит использовать, остаётся прежним:
|
||
|
||
- Чистая архитектура с шаблоном MVVM (ViewModel и LiveData для связи UI со слоем данных).
|
||
- Retrofit для выполнения сетевых запросов.
|
||
- SharedPreference для сохранения параметров фильтрации и Room для хранения избранных вакансий.
|
||
- Корутины для асинхронных задач и многопоточности.
|
||
- Внедрение зависимостей (репозитории, интеракторы и ViewModel) при помощи Koin.
|
||
- Jetpack Navigation Component и BottomNavigationView для реализации навигации в приложении.
|
||
|
||
**КОНЕЦ КАТА**
|
||
```
|
||
|
||
### Блоки-галереи
|
||
|
||
Блоки-галереи предназначены для показа нескольких картинок в одном блоке. С помощью таких блоков очень удобно
|
||
демонстрировать дизайны экранов, последовательности визуальных инструкций.
|
||
|
||
На Платформе эти блоки выглядят так:
|
||
|
||
|
||
|
||
В коде урока блок-галереи начинается строкой `**БЛОК-ГАЛЕРЕЯ**`, далее следует перечисление картинок в упорядоченном
|
||
списке. Блок заканчивается строкой `**КОНЕЦ БЛОКА-ГАЛЕРЕИ**`.
|
||
|
||
```markdown
|
||
**БЛОК-ГАЛЕРЕЯ**
|
||
|
||
1. 
|
||
2. 
|
||
3. 
|
||
4. 
|
||
|
||
**КОНЕЦ БЛОКА-ГАЛЕРЕИ**
|
||
```
|
||
|
||
### Блоки-квизы
|
||
|
||
Блоки с квизами предназначены для описания дополнительных проверочных заданий. Полный перечень возможных типов квизов
|
||
можно
|
||
увидеть [по ссылке](https://docs.google.com/presentation/d/1gerL6XE4pEzzD2_Y_wQHqNaixg152R2eFTP26fvmc20/edit#slide=id.gfe8352e58f_0_1528).
|
||
|
||
#### Одиночный выбор
|
||
|
||
- Самая простая механика — обычный тестовый вопрос.
|
||
- Принимается текст, формулы, картинки и код в качестве вариантов ответа и фидбека.
|
||
- Можно показать студенту фидбек к каждому ответу, чтобы объяснить ему что-то
|
||
- Надёжный как швейцарские часы!
|
||
- Немного скучный.
|
||
|
||
На Платформе эти блоки выглядят так:
|
||
|
||
|
||
|
||
|
||
|
||
В коде урока блок квиза с множественным выбором начинается строкой `**КВИЗ** (Одиночный выбор)`, далее следует текст
|
||
задания. Текст заданий помимо отформатированного текста может содержать изображения, блоки с кодом. После описания
|
||
задания идёт перечисление вариантов ответа. Каждый вариант начинается символом чекбокса `- [ ] `, далее следует текст
|
||
варианта. После описания каждого варианта ответа **должно быть пояснение к ответу**. Правильные ответы отмечаются
|
||
строкой `(ПРАВИЛЬНЫЙ ОТВЕТ)`. Варианты ответа могут быть и пояснения могут быть текстом с форматированием. Весь блок
|
||
заканчивается строкой `**КОНЕЦ КВИЗА**`.
|
||
|
||
```markdown
|
||
**КВИЗ** (Одиночный выбор)
|
||
|
||
Выберите атрибуты, которые нужно поставить элементу, чтобы растянуть его по высоте от низа элемента `myElement` до
|
||
нижнего края родительского контейнера:
|
||
|
||
- [ ] `layout_below="@id/myElement` и `layout_alignParentBottom="true"`
|
||
|
||
(ПРАВИЛЬНЫЙ ОТВЕТ) Верно!
|
||
|
||
- [ ] `layout_alingBottom="@id/myElement` и `layout_alignParentBottom="true"`
|
||
|
||
Первый атрибут привяжет **нижний** край нашего элемента к нижнему краю `myElement`, а второй привяжет нижний край
|
||
элемента к нижнему краю родительского контейнера. Чтобы исправить код, нам нужно привязать верхний край нашего элемента
|
||
к нижнему краю `myElement`, то есть воспользоваться атрибутом `layout_below="@id/myElement`.
|
||
|
||
- [ ] `layout_below="@id/myElement` и `layout_above="parent"`
|
||
|
||
Первый атрибут привяжет верхний край нашего элемента к нижнему краю `myElement`, а второй атрибут в `RelativeLayout` не
|
||
может принимать значение `parent`. Чтобы привязать нижний край нашего элемента к нижнему краю родительского контейнера,
|
||
нам нужен атрибут `layout_alignParentBottom="true"`.
|
||
|
||
**КОНЕЦ КВИЗА**
|
||
```
|
||
|
||
Если у квиза есть дополнительное пояснение, которое следует показать после выбора ответа, мы помещаем его текст перед
|
||
окончанием квиза, вот так:
|
||
|
||
```markdown
|
||
// Дополнительное пояснение после ответа
|
||
|
||
Мы не можем записать объекты в `SharedPreferences` напрямую. Сначала нам нужно представить объект в виде строки, а потом
|
||
записать эту строку.
|
||
```
|
||
|
||
#### Множественный выбор
|
||
|
||
- Работает по тем же принципам, что и одиночный выбор.
|
||
- Студенту предлагается ряд вариантов, и он может выбрать несколько вариантов в качестве ответа.
|
||
|
||
На Платформе эти блоки выглядят так:
|
||
|
||
|
||
|
||
В коде урока блок квиза с множественным выбором начинается строкой `**КВИЗ** (Множественный выбор)`, далее следует текст
|
||
задания. Текст заданий помимо отформатированного текста может содержать изображения, блоки с кодом. После описания
|
||
задания идёт перечисление вариантов ответа. Каждый вариант начинается символом чекбокса `- [ ] `, далее следует текст
|
||
варианта. После описания каждого варианта ответа **должно быть пояснение к ответу**. Правильные ответы отмечаются
|
||
строкой `(ПРАВИЛЬНЫЙ ОТВЕТ)`. Варианты ответа могут быть и пояснения могут быть текстом с форматированием. Весь блок
|
||
заканчивается строкой `**КОНЕЦ КВИЗА**`.
|
||
|
||
```markdown
|
||
**КВИЗ** (Множественный выбор)
|
||
|
||
Каких атрибутов центрирования нет в `RelativeLayout`?
|
||
|
||
- [ ] `layout_center`
|
||
|
||
(ПРАВИЛЬНЫЙ ОТВЕТ) Верно! Такого атрибута у дочерних элементов `RelativeLayout` нет.
|
||
Зато есть `layout_centerInParent`, который позволит отцентрировать элемент внутри родительского контейнера.
|
||
|
||
- [ ] `layout_centerInParent`
|
||
|
||
У дочерних элементов `RelativeLayout` появляется атрибут `layout_centerInParent`, который позволит отцентрировать
|
||
элемент внутри родительского контейнера.
|
||
|
||
- [ ] `layout_centerInChild`
|
||
|
||
(ПРАВИЛЬНЫЙ ОТВЕТ) Верно! Такого атрибута у дочерних элементов `RelativeLayout` нет. Зато есть `layout_centerInParent`,
|
||
который позволит отцентрировать элемент внутри родительского контейнера.
|
||
|
||
- [ ] `layout_centerBoth`
|
||
|
||
(ПРАВИЛЬНЫЙ ОТВЕТ) Верно! Такого атрибута у дочерних элементов `RelativeLayout` нет. Зато есть отдельные
|
||
атрибуты `layout_centerVertical` и `layout_centerHorizontal`, которые позволят отцентрировать элемент только по
|
||
вертикали либо только по горизонтали.
|
||
|
||
- [ ] `layout_centerVertical`
|
||
|
||
У дочерних элементов `RelativeLayout` появляется атрибут `layout_centerVertical`, который позволит отцентрировать
|
||
элемент только во вертикали.
|
||
|
||
- [ ] `layout_centerHorizontal`
|
||
|
||
У дочерних элементов `RelativeLayout` появляется атрибут `layout_centerHorizontal`, который позволит отцентрировать
|
||
элемент только по горизонтали.
|
||
|
||
**КОНЕЦ КВИЗА**
|
||
```
|
||
|
||
Если вариант ответа не помещается в одну строку, то после символа чекбокса мы пропускаем строку и описываем вариант:
|
||
|
||
```markdown
|
||
- [ ]
|
||
|
||
```xml
|
||
|
||
<TextView
|
||
android:id="@+id/button3"
|
||
style="@style/Digit"
|
||
android:layout_alignTop="@id/button2"
|
||
android:layout_marginStart="20dp"
|
||
android:layout_marginTop="20dp"
|
||
android:layout_toEndOf="@id/button2"
|
||
android:text="3" />
|
||
```
|
||
|
||
(ПРАВИЛЬНЫЙ ОТВЕТ) Верно! Цифра 3 расположена справа от кнопки `button2` (`layout_toEndOf="@id/button2"`) и привязана к
|
||
верхней части той же кнопки (отсюда и `layout_alignTop`).
|
||
|
||
#### Выбор из списка
|
||
|
||
- Студенту надо выбрать правильный ответ к каждому вопросу/картинке.
|
||
- Фидбек к каждому ответу виден студенту.
|
||
- Можно сформулировать как задачку из серии «расставьте в правильном порядке».
|
||
- Может выглядеть несколько громоздко.
|
||
- Позволяет спросить обо всём и сразу.
|
||
|
||
TBD
|
||
|
||
#### Текстовое поле
|
||
|
||
- Студенту должен ввести слова или числа в поле.
|
||
- Этот квиз может идти без проверки.
|
||
- Можно запросить точный ответ или прописать несколько вариантов как правильные.
|
||
- Хорошо подходит для математических задачек на расчёты.
|
||
- Меньше подходит для текстов — их долго и сложно писать.
|
||
|
||
TBD
|
||
|
||
#### Квиз-макароны
|
||
|
||
- Элементы нужно корректно соединить между собой линиями.
|
||
- Каждой карточке — по одному соответствию.
|
||
- Общий фидбек + правильное соответствие к каждой карточке слева.
|
||
- Поддерживает картинки.
|
||
- Выглядит очень наглядным.
|
||
- Плохо дружит с широкими и длинным текстом.
|
||
|
||
На Платформе такой блок выглядит следующим образом:
|
||
|
||
|
||
|
||
|
||
|
||
В коде урока квизы-макароны имеют следующий формат: блок начинается с `**КВИЗ** (Макароны)`, затем следует описание
|
||
задачи. Далее перечисляем список вариантов в левой колонке (предваряя комментарием `// Варианты в левой колонке`),
|
||
потом - список вариантов в правой колонке (предваряя комментарием `// Варианты в правой колонке`). После этого следует
|
||
секция с правильными ответами, там мы перечисляем номера элементов в левой колонке, добавляем стрелочку и указываем
|
||
номер соответствия в правой колонке. И, наконец, добавляем опциональный текст успеха, который будет показываться после
|
||
выполнения задачи (предваряя комментарием `// Текст успеха`): Если текста успеха нет, то нет и комментария.
|
||
|
||
```markdown
|
||
**КВИЗ (Макароны)**
|
||
|
||
Сопоставьте названия шаблонов и их назначениями:
|
||
|
||
// Варианты в левой колонке
|
||
|
||
1. Adapter
|
||
2. Singleton
|
||
3. Observer
|
||
|
||
// Варианты в правой колонке
|
||
|
||
1. реализует у класса механизм, который позволяет объекту этого класса получать оповещения об изменении состояния других
|
||
объектов и наблюдать за ними.
|
||
2. c его помощью создаётся только один объект класса.
|
||
3. предназначен для организации использования функций объекта через специально созданный интерфейс
|
||
|
||
// Правильные ответы
|
||
|
||
- 1 --> 3
|
||
- 2 --> 2
|
||
- 3 --> 1
|
||
|
||
// Текст успеха
|
||
|
||
Наши помощники!
|
||
|
||
**КОНЕЦ КВИЗА**
|
||
```
|
||
|
||
#### Карточки
|
||
|
||
- Разные ответы нужно распределить по категориям.
|
||
- Каждая карточка относится к одной категории.
|
||
- Фидбек к каждому ответу.
|
||
- Не больше четырёх категорий.
|
||
- Выглядит очень наглядным.
|
||
- Подходит для небольшого круга вопросов.
|
||
|
||
На Платформе такой блок выглядит следующим образом:
|
||
|
||
|
||
|
||
|
||
|
||
В коде урока квизы-карточки имеют следующий формат: блок начинается с `**КВИЗ (Карточки)**`, затем следует описание
|
||
задачи, далее идёт список, где элементы первого уровня определяют категории, по которым нужно будет распределять
|
||
карточки, а элементы второго уровня обозначают ответы для этой категории. Блок заканчивается строкой `**КОНЕЦ КВИЗА**`.
|
||
|
||
```markdown
|
||
**КВИЗ** (Карточки)
|
||
|
||
Расположите методы жизненного цикла фрагмента в подходящих группах.
|
||
|
||
- Методы ЖЦ объекта фрагмента
|
||
|
||
- `onDestroy`
|
||
- `onStop`
|
||
- `onPause`
|
||
- `onResume`
|
||
- `onStart`
|
||
- `onCreate`
|
||
|
||
- Методы ЖЦ `View` фрагмента
|
||
|
||
- `onDestroyView`
|
||
- `onViewCreated`
|
||
- `onCreateView`
|
||
|
||
- Методы привязки фрагмента к `Activity`
|
||
|
||
- `onDetach`
|
||
- `onAttach`
|
||
|
||
**КОНЕЦ КВИЗА**
|
||
```
|
||
|
||
#### Сборная строка
|
||
|
||
- Ответы нужно расположить в правильном порядке.
|
||
- Общий фидбек.
|
||
- Выглядит очень наглядным.
|
||
- Ответы должны быть не очень длинными.
|
||
|
||
На Платформе такой блок выглядит следующим образом:
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
В коде урока квизы со сборной строкой имеют следующий формат: блок начинается с `**КВИЗ (Сборная строка)**`, затем
|
||
следует описание задачи, далее идёт строчка вида `// Список строк`, после неё список, где все элементы расположены
|
||
в **правильном** порядке. Далее следует строка `// Текст успеха`, и затем текст, который будет показываться в случае
|
||
успеха или ошибки. Блок заканчивается строкой `**КОНЕЦ КВИЗА**`.
|
||
|
||
```markdown
|
||
**КВИЗ** (Сборная строка)
|
||
|
||
Дополните код и составьте корректный запрос записи массива в `SharedPreferences`, где данные получаются
|
||
методом `getUsers`.
|
||
|
||
// Список строк
|
||
|
||
- `sharedPreferences.edit()`
|
||
- `putString(USER_LIST_KEY, Gson().toJSON(getUsers()))`
|
||
- `.apply()`
|
||
|
||
// Текст успеха
|
||
|
||
Ох уж этот код!
|
||
|
||
**КОНЕЦ КВИЗА**
|
||
```
|
||
|
||
### Формат сниппетов
|
||
|
||
Блок, в котором студент тренируется в написании кода (и может его запустить), по ходу чтения урока.
|
||
|
||
Можно использовать для решения небольших задач, когда студент меняет код и проверяет результат.
|
||
А так же, может посмотреть подсказки и авторское решение.
|
||
|
||
На Платформе такой блок выглядит следуюшим образом:
|
||
|
||
|
||
|
||
Или ещё:
|
||
|
||
|
||
|
||
Обратите внимание, что текстовое задание не является частью этого блока. Поэтому располагаем задание
|
||
перед этим блоком (а не внутри).
|
||
|
||
Как выглядит текст успеха:
|
||
|
||
|
||
|
||
Так же можно использовать блок для запуска кода, если хотите, чтобы студент просто поигрался с кодом:
|
||
|
||
|
||
|
||
Для уменьшения кода в уроках, выносим сниппеты в отдельные файлы.
|
||
|
||
#### В коде урока
|
||
|
||
```markdown
|
||
**СНИППЕТ** [Name of snippet 1](../code/snippet/01_piggy_bank.md)
|
||
|
||
...
|
||
|
||
**СНИППЕТ** [Name of snippet 2](../code/snippet/02_numbers.md)
|
||
**СНИППЕТ** [Name of snippet 3](../code/snippet/02_letters.md)
|
||
```
|
||
|
||
#### В файле со сниппетом
|
||
|
||
Внутри этих файлов используем следующий формат:
|
||
|
||
- Блок начинается с **НАЗВАНИЯ**;
|
||
- Далее идёт **прекод** - это код, который изначально установлен в сниппет. То, с какого места студент начинает свою
|
||
работу;
|
||
- **Подсказки** (используется для решения задач, но опционально) - текст, с подсказками для студента. Будет отображён в
|
||
сниппите после нажатия на кнопку "подсказка"
|
||
- **Авторское решение** (обязательно, если сниппет не просто для запуска прекода) - код, который будет подставлен в
|
||
сниппет, после нажатия на кнопку "авторское решение";
|
||
- **Текст успеха** (обязательно, если сниппет не просто для запуска прекода) - текст, который увидит студент, когда у
|
||
него всё получится
|
||
- **НЕ ДЛЯ СТУДЕНТА** - блок с текстом. Не для студента, а для того, кто пишет проверки для сниппитов. Тут можно сделать
|
||
акцент на важных вещах, которые надо проверить после запуска кода студента.
|
||
|
||
P.S. Далее идёт блок с разбитием на мини-блоки, потому что в MD в блоке с кодом нельзя вставлять другие
|
||
блоки с кодом. Но подразумевается, что это единый документ.
|
||
|
||
Сниппет для решения небольших задач:
|
||
|
||
```markdown
|
||
# НАЗВАНИЕ СНИППЕТА
|
||
|
||
## Прекод
|
||
```
|
||
|
||
```kotlin
|
||
val moneyAmmount = 0
|
||
// ...
|
||
moneyAmmount += 100_000_000_000
|
||
// ...
|
||
println("Денег на вашем счёте: " + moneyAmmount)
|
||
```
|
||
|
||
```markdown
|
||
## Подсказки
|
||
|
||
- В Kotlin два типа переменных: изменяемые `var` и неизменяемые `val`.
|
||
- В Kotlin переменные, указанные как целое значение и не превышающее максимальное для `Int`, автоматически будут
|
||
определены как `Int`.
|
||
- Вы можете явно указать тип `Long`, добавив после значения переменной литеру `L`.
|
||
|
||
## Авторское решение
|
||
```
|
||
|
||
```kotlin
|
||
var moneyAmmount = 0L
|
||
moneyAmmount += 100_000_000_000
|
||
println("Денег на вашем счёте: " + moneyAmmount)
|
||
```
|
||
|
||
```markdown
|
||
## Текст успеха
|
||
|
||
Ура, вы справились!
|
||
|
||
# НЕ ДЛЯ СТУДЕНТА !!!
|
||
|
||
- Если запускается и выводит текст, то всё окей.
|
||
- Если при запуске выводится "Val cannot be reassigned" - вывести ошибку "Нельзя изменить значение иммутабельной
|
||
переменной".
|
||
- Если при запуске ошибка "Type mismatch: inferred type is Long but Int was expected" - вывести ошибку "Переменная типа
|
||
Int не вместит в себя столь огромное число".
|
||
```
|
||
|
||
### Формат тренажёра
|
||
|
||
В целом, всё аналогично сниппетам: делаем в отдельном файле. Но в отличии от сниппетов, условие
|
||
задачи уже пишется в файле тренажёра, потому что по разметке так и получается, ведь тренажёр - это
|
||
как будто отдельный урок.
|
||
|
||
На Платформе такой блок выглядит следуюшим образом:
|
||
|
||
|
||
|
||
Так выглядят подсказки:
|
||
|
||
|
||
|
||
Как выглядит текст успеха и ошибки (после нажатия на `Проверить`):
|
||
|
||
|
||
|
||
|
||
|
||
#### В коде урока
|
||
|
||
```markdown
|
||
**ТРЕНАЖЁР** [Name of trainer](../code/trainers/02_numbers.md)
|
||
```
|
||
|
||
#### В файле с тренажёром
|
||
|
||
P.S. Тут тоже с разбиением на мини-блоки, но подразумевается, что это единый документ.
|
||
|
||
```markdown
|
||
# Название тренажёра
|
||
|
||
## Задача
|
||
|
||
Джуниор разработчику Иннокентию 30 лет. Иннокентий попал в команду разработки приложения одного крупного банка, в его
|
||
команде есть программисты, возраст которых 25, 36, и 21 год. Какой средний возраст разработчика в команде Иннокентия?
|
||
|
||
- Объявите мутабельную переменную `averageAge`.
|
||
- Укажите возраст Иннокентия в качестве начального значения.
|
||
- В иммутабельную переменную `numberOfDevelopers` поместите количество разработчиков в команде.
|
||
- Вычислите средний возраст разработчика, полученное значение выведите на экран.
|
||
|
||
## Прекод
|
||
```
|
||
|
||
```kotlin
|
||
fun main() {
|
||
// объявите мутабельную переменную averageAge со значением возраста Инокентия 30 лет
|
||
// объявите иммутабельную переменную numberOfDevelopers с количеством разработчиков в команде
|
||
|
||
// пересчитайте averageAge равную среднему возрасту (остальных участников 25, 36, и 21 лет)
|
||
|
||
// выведите averageAge
|
||
}
|
||
```
|
||
|
||
```markdown
|
||
## Подсказки
|
||
|
||
- для вычисления среднего возраста вам потребуется среднее арифметическое — сумма возрастов, поделённая на количество
|
||
разработчиков в команде.
|
||
|
||
## Авторское решение
|
||
```
|
||
|
||
```kotlin
|
||
fun main() {
|
||
var averageAge = 30
|
||
val numberOfDevelopers = 4
|
||
|
||
averageAge = (averageAge + 25 + 36 + 21) / numberOfDevelopers
|
||
|
||
println(averageAge)
|
||
}
|
||
```
|
||
|
||
```markdown
|
||
## Текст успеха
|
||
|
||
Прекрасно, Инокентий не так уж стар! 28 лет — отличный возраст для начала карьеры разработчика!
|
||
|
||
# НЕ ДЛЯ СТУДЕНТА !!!
|
||
|
||
- проверить, что объявлена как минимум 1 переменная `val`.
|
||
- проверить результат вывода = 28.
|
||
``` |