Yandex-Practicum/mobile-android

Fork 0

Files

T

p.strelchenko a7a54f4616 [main] Ослабляет линтер на названия файлов

2024-09-04 20:28:56 +05:00

54 KiB

Raw Permalink Blame History

Код-стайл оформления кода уроков

Этот документ содержит в себе описание согласованного код-стайла для оформления текстов уроков Яндекс.Практикума.

Структура репозитория

В общем виде структура репозитория выглядит так:

- .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

Содержимое папок с уроками

Каждому спринту курса соответствует отдельная папка в корне проекта (например: 01.Sprint, 02.Sprint, etc). Цифра обозначает номер спринта.

- 01. Спринт
- 02. Спринт
- ...

Каждой теме соответствует отдельная папка внутри папки спринта (например: 02.Sprint/01. Методы/, 02.Spring/02. Классы и объекты, etc). Цифра возле названия темы соответствует порядковому номеру темы внутри спринта.

- 01. Спринт:
    - 01. Начало платного обучения
    - 02. История Java
    - 03. Объявление переменных
    - ...
- 02. Спринт:
    - 01. Методы
    - 02. Классы и объекты
    - 03. Git для самых маленьких
    - ...
- ...

Каждому уроку внутри темы соответствует отдельный MD-файл с названием урока ( например: 03.Sprint/01. Массивы, списки, итераторы/01. Массивы.md). Цифра возле названия урока соответствует порядковому номеру урока внутри темы спринта.

- 01. Спринт:
    - 01. Начало платного обучения:
        - 01. Снова здравствуйте!.md
        - 02. Начало спринта № 1.md
    - 02. История Java:
        - 01. Java. Предпосылки.md
        - 02. Составляющие инфраструктуры Java.md
        - 03. Как Android встретила Java.md
    - 03. Объявление переменных:
        - ...
- ...

Внутри папки с темой может находиться папка assets, предназначенная для хранения всех дополнительных ресурсов, связанных с конкретной темой. К ресурсам относятся: скриншоты, схемы, картинки от иллюстратора, видео, гиф-анимации и исходники изображений.

- 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 должны находиться исходники скриншотов и исходники схем, которым требуется перерисовка.

Внутри папки с темой может находиться папка code, предназначенная для хранения кода тренажёров (trainers) и сниппетов (snippets), связанных с конкретной темой. Название файла должно быть осмысленным и иметь префикс snippet или trainer.

- 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 не портила оформление текста.

Жирный шрифт

Текст, который нужно выделить жирным шрифтом, выделяется двумя символами-звёздочками (*) с двух сторон:

Когда мы смотрим на макет, нам нужно понимать, как отдельные элементы интерфейса (баннеры, кнопки, иконки) расположены
**друг относительно друга**.

Код внутри строки

Текст, который нужно выделить как код, выделяется одинарными косыми кавычками (`текст`):

В документации вы можете увидеть требование передавать в запросах заголовок `User-Agent`. Этот заголовок может содержать
информацию о типе устройства, операционной системе, используемой версии приложения и другие детали. Получается что-то
вроде визитной карточки вашего устройства.

Блоки кода

Блоки кода начинаются тройным повторением одинарной косой кавычки (`) и обязательным указанием языка для этого блока. Код внутри блока должен соответствовать стандартам языка программирования. Блок заканчивается тройным повторением одинарной косой кавычки.

<?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

Стандарты языков программирования

Изображения, видео, gif

Общее

Разрешённые расширения файлов: .png, .gif и .mp4.
Файлы-исходники, которые находятся в папке raw, должны иметь в названии суффикс __raw. После того как исходник будет обработан и положен в папку img, название нового изображения должно совпадать с именем исходника за исключением суффикса __raw.
Скриншоты Android Studio делаются в Dark-теме (в старом UI - тема Darcula).
Скриншоты Github делаются в тёмной теме.
Изображения, связанные с Android Studio (скриншоты выбора проекта, скриншоты, связанные с отображением кода, etc), должны быть отмечены в специальном перечне.

DO:

01_splash_screen.png.
Skrinshot_09.png.
here_we_go_again.png.

DON'T:

всё очень плохо.png.
скрин 1.png.

Код-стайл

Блок с картинкой или видео начинается строкой **КАРТИНКА** (или **ВИДЕО**), затем идёт пустая строка, а потом описывается относительный путь до картинки внутри репозитория.

**КАРТИНКА**

![Расположили элементы сверху и снизу от центральной кнопки](./assets/img/some_picture.png)

**ВИДЕО**

![Демонстрация нижней навигации](./assets/video/bottom_navigation_demo.mp4)

Если картинка или видео взяты с платформы посредством выполнения скрипта актуализации, блок с начинается строкой **КАРТИНКА (ВЗЯТО С ПЛАТФОРМЫ)** или **ВИДЕО (ВЗЯТО С ПЛАТФОРМЫ)**, затем идёт пустая строка, а потом описывается ссылка на картинку.

**КАРТИНКА (ВЗЯТО С ПЛАТФОРМЫ)**

![image](https://pictures.s3.yandex.net:443/resources/Skrinshot_06_1682414328.png)

**ВИДЕО (ВЗЯТО С ПЛАТФОРМЫ)**

![video](https://code.s3.yandex.net/Mobile/Android/%D0%92%D0%B8%D0%B4%D0%B5%D0%BE/ndr.mp4)

Техническое задание для иллюстратора начинается упоминанием Github-ника иллюстратора, затем идёт описание задания.

@sashasketchit Нарисовать аналог в нашей тематике.

@sashasketchit Может тут стоить нарисовать ЭНДИ с испуганным лицом и капельками пота на лице или сидящим за столом с
водкой и сигаретой (как в том меме).

Каждое изображение в коде должно иметь осмысленный альтернативный текст (Пока что на Платформе не описывается альтернативный текст, поэтому в качестве описания картинки после актуализации текста пишется просто image.).

![Хомяк навигационный](https://pictures.s3.yandex.net:443/resources/01khomiak_instrumenty_navigatsii_1683199285.png)

![Схема "Чистой архитектуры"](https://pictures.s3.yandex.net:443/resources/Clean_architecture_scheme_1676879485.png)

DON'T

![img](https://pictures.s3.yandex.net:443/resources/01khomiak_instrumenty_navigatsii_1683199285.png)

![](https://pictures.s3.yandex.net:443/resources/Clean_architecture_scheme_1676879485.png)

Особое выделение блоков на Платформе

На Платформе есть возможность выделять блоки текста множеством разных способов. Чтобы при переносе контента урока из репозитория на Платформу эти блоки не потерялись, нужно корректно выделять их в тексте Markdown-файлов.

Термин для глоссария

Мы можем выделять термины таким образом, чтобы при наведении на них, мы могли отобразить дополнительные пояснения.

На Платформе это выглядит так:

Блоки с цитатами

Блоки с цитатами предназначены для дополнительного выделения некоторого цитируемого текста, например, в тексте урока приводится пример технического задания, или пример рассуждений какого-то человека.

На Платформе эти блоки выглядят так:

В коде урока блок с цитатами начинается строкой **БЛОК ЦИТАТЫ**, далее следует текст блока. Каждая строка блока начинается с символа закрывающей угловой скобки (>). Блок заканчивается строкой **КОНЕЦ БЛОКА ЦИТАТЫ**.

**БЛОК ЦИТАТЫ**

>
> Вот эта надпись находится сверху от кнопки.
>
> Эта картинка расположена слева от заголовка.
>
> Три иконки в ряд, а вместе они под основным текстом и по центру экрана.

**КОНЕЦ БЛОКА ЦИТАТЫ**

Блок пояснения

На Платформе есть возможность выделить блок текста для его большей заметности.

На Платформе эти блоки выглядят так:

В коде урока блок пояснения начинается строкой **БЛОК**, далее, если хотим добавить заголовок - пишем его текст после начальной строки. Затем добавляется пустая строка, после которой начинается описание текста блока. Текст блока может содержать только отформатированный текст. Блок заканчивается строкой **КОНЕЦ БЛОКА**.

**БЛОК**

Подсказки для продвинутых задач развёрнутые и направляют к конкретным решениям, поэтому вы вполне можете с ними
справиться. Если вы придёте к решению самостоятельно, то это уровень специалиста, достойный особого внимания
работодателей.

**КОНЕЦ БЛОКА**

Или блок с заголовком:

**БЛОК** 💡Совет от разработчика

В `RelativeLayout` дочерние элементы по умолчанию привязаны к левому верхнему краю контейнера, как будто бы применены
атрибуты `layout_alignParentTop="true"` и `layout_alignParentStart="true"`.

Мы рекомендуем всегда явно описывать все желаемые атрибуты, чтобы избежать недоразумений.

**КОНЕЦ БЛОКА**

Блок-диалог

На Платформе есть возможность выразить часть текста как реплики диалога между студентом и роботом Энди. Это полезно, когда мы хотим немного разбавить серьёзность урока, добавить какие-то интересные пояснения с короткой подводкой.

На Платформе это выглядит так:

В коде урока блок-диалог начинается строкой **ДИАЛОГ**. Далее мы указываем реплики в диалоге отдельными строками текста. В начале реплики мы указываем "автора" сообщения (если это бот "Энди", то **ЭНДИ**, иначе **СТУДЕНТ**), а дальше отформатированный текст в двойных кавычках (").

**ДИАЛОГ**

**СТУДЕНТ** "С вертикальными и горизонтальными элементами мы уже работали!"
**ЭНДИ** "Как растянуть кнопки, тоже знаем!"

**КОНЕЦ ДИАЛОГА**

Если же мы хотим добавить одиночную реплику, без диалога, то указываем просто автора реплики, а рядом - текст.

**СТУДЕНТ** "Выглядит реализуемо! "

Если мы хотим добавить несколько фраз от одного и того же автора, оформляем это так: начинаем строчкой **МОНОЛОГ ИМЯ_АВТОРА**, далее идут реплики от лица автора, и заканчиваем строкой **КОНЕЦ МОНОЛОГА**.

**МОНОЛОГ ЭНДИ**

С родительскими контейнерами познакомились!
А что дальше?

**КОНЕЦ МОНОЛОГА**

Блок-реплика

На Платформе есть возможность описать кнопку-призыв к действию. Обычно эта кнопка приводит к появлению блока с диалогом.

На Платформе это выглядит так:

В коде урока такая кнопка описывается строкой **КНОПКА-РЕПЛИКА**, после чего идёт отформатированный текст.

**КНОПКА-РЕПЛИКА** С вертикальными и горизонтальными элементами мы уже работали!

Блок-переход на следующий урок

На Платформе есть возможность описать кнопку для перехода на следующий урок. Это может быть как простая фраза, так и одно слово.

На Платформе это выглядит так:

В коде урока такая кнопка описывается строкой **КНОПКА-ПЕРЕХОД**, после чего идёт отформатированный текст.

**КНОПКА-ПЕРЕХОД** Вперёд!

Блок для скрытия/показа контента

На Платформе есть возможность оборачивать контент в блоки с возможностью скрытия/показа контента. Это бывает полезно, когда мы хотим дать какую-то опциональную теорию или же описать блок, содержимое которого не должно быть сразу видно ( пример: критерии дипломного проекта с подсказками декомпозиции).

На Платформе эти блоки выглядят так:

В коде урока блок для скрытия/показа контента начинается строкой **СПРЯТАТЬ ПОД КАТ**, на этой же строке указываем заголовок блока, который будет виден пользователю до разворачивания блока. Далее следует текст скрытого блока. Текст блока может содержать картинки, списки, блоки с кодом и т.д. Блок заканчивается строкой **КОНЕЦ КАТА**.

**СПРЯТАТЬ ПОД КАТ** Основная логика приложения и UI

Структура вашего будущего приложения похожа на структуру знакомых Playlist Maker и приложения для поиска фильмов. Общий
набор инструментов, которые вам предстоит использовать, остаётся прежним:

- Чистая архитектура с шаблоном MVVM (ViewModel и LiveData для связи UI со слоем данных).
- Retrofit для выполнения сетевых запросов.
- SharedPreference для сохранения параметров фильтрации и Room для хранения избранных вакансий.
- Корутины для асинхронных задач и многопоточности.
- Внедрение зависимостей (репозитории, интеракторы и ViewModel) при помощи Koin.
- Jetpack Navigation Component и BottomNavigationView для реализации навигации в приложении.

**КОНЕЦ КАТА**

Блоки-галереи

Блоки-галереи предназначены для показа нескольких картинок в одном блоке. С помощью таких блоков очень удобно демонстрировать дизайны экранов, последовательности визуальных инструкций.

На Платформе эти блоки выглядят так:

В коде урока блок-галереи начинается строкой **БЛОК-ГАЛЕРЕЯ**, далее следует перечисление картинок в упорядоченном списке. Блок заканчивается строкой **КОНЕЦ БЛОКА-ГАЛЕРЕИ**.

**БЛОК-ГАЛЕРЕЯ**

1. ![image](https://pictures.s3.yandex.net:443/resources/skrin_04_search_01_1683201744.png)
2. ![image](https://pictures.s3.yandex.net:443/resources/skrin_04_mt2_02_1683201751.png)
3. ![image](https://pictures.s3.yandex.net:443/resources/skrin_04_mt1_03_1683201757.png)
4. ![image](https://pictures.s3.yandex.net:443/resources/skrin_04_settings_04_1683201763.png)

**КОНЕЦ БЛОКА-ГАЛЕРЕИ**

Блоки-квизы

Блоки с квизами предназначены для описания дополнительных проверочных заданий. Полный перечень возможных типов квизов можно увидеть по ссылке.

Одиночный выбор

Самая простая механика — обычный тестовый вопрос.
Принимается текст, формулы, картинки и код в качестве вариантов ответа и фидбека.
Можно показать студенту фидбек к каждому ответу, чтобы объяснить ему что-то
Надёжный как швейцарские часы!
Немного скучный.

На Платформе эти блоки выглядят так:

В коде урока блок квиза с множественным выбором начинается строкой **КВИЗ** (Одиночный выбор), далее следует текст задания. Текст заданий помимо отформатированного текста может содержать изображения, блоки с кодом. После описания задания идёт перечисление вариантов ответа. Каждый вариант начинается символом чекбокса - [ ] , далее следует текст варианта. После описания каждого варианта ответа должно быть пояснение к ответу. Правильные ответы отмечаются строкой (ПРАВИЛЬНЫЙ ОТВЕТ). Варианты ответа могут быть и пояснения могут быть текстом с форматированием. Весь блок заканчивается строкой **КОНЕЦ КВИЗА**.

**КВИЗ** (Одиночный выбор)

Выберите атрибуты, которые нужно поставить элементу, чтобы растянуть его по высоте от низа элемента `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"`.

**КОНЕЦ КВИЗА**

Если у квиза есть дополнительное пояснение, которое следует показать после выбора ответа, мы помещаем его текст перед окончанием квиза, вот так:

// Дополнительное пояснение после ответа

Мы не можем записать объекты в `SharedPreferences` напрямую. Сначала нам нужно представить объект в виде строки, а потом
записать эту строку.

Множественный выбор

Работает по тем же принципам, что и одиночный выбор.
Студенту предлагается ряд вариантов, и он может выбрать несколько вариантов в качестве ответа.

На Платформе эти блоки выглядят так:

В коде урока блок квиза с множественным выбором начинается строкой **КВИЗ** (Множественный выбор), далее следует текст задания. Текст заданий помимо отформатированного текста может содержать изображения, блоки с кодом. После описания задания идёт перечисление вариантов ответа. Каждый вариант начинается символом чекбокса - [ ] , далее следует текст варианта. После описания каждого варианта ответа должно быть пояснение к ответу. Правильные ответы отмечаются строкой (ПРАВИЛЬНЫЙ ОТВЕТ). Варианты ответа могут быть и пояснения могут быть текстом с форматированием. Весь блок заканчивается строкой **КОНЕЦ КВИЗА**.

**КВИЗ** (Множественный выбор)

Каких атрибутов центрирования нет в `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`, который позволит отцентрировать
элемент только по горизонтали.

**КОНЕЦ КВИЗА**

Если вариант ответа не помещается в одну строку, то после символа чекбокса мы пропускаем строку и описываем вариант:

- [ ]

```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

Квиз-макароны

Элементы нужно корректно соединить между собой линиями.
Каждой карточке — по одному соответствию.
Общий фидбек + правильное соответствие к каждой карточке слева.
Поддерживает картинки.
Выглядит очень наглядным.
Плохо дружит с широкими и длинным текстом.

На Платформе такой блок выглядит следующим образом:

В коде урока квизы-макароны имеют следующий формат: блок начинается с **КВИЗ** (Макароны), затем следует описание задачи. Далее перечисляем список вариантов в левой колонке (предваряя комментарием // Варианты в левой колонке), потом - список вариантов в правой колонке (предваряя комментарием // Варианты в правой колонке). После этого следует секция с правильными ответами, там мы перечисляем номера элементов в левой колонке, добавляем стрелочку и указываем номер соответствия в правой колонке. И, наконец, добавляем опциональный текст успеха, который будет показываться после выполнения задачи (предваряя комментарием // Текст успеха): Если текста успеха нет, то нет и комментария.

**КВИЗ (Макароны)**

Сопоставьте названия шаблонов и их назначениями:

// Варианты в левой колонке

1. Adapter
2. Singleton
3. Observer

// Варианты в правой колонке

1. реализует у класса механизм, который позволяет объекту этого класса получать оповещения об изменении состояния других
   объектов и наблюдать за ними.
2. c его помощью создаётся только один объект класса.
3. предназначен для организации использования функций объекта через специально созданный интерфейс

// Правильные ответы

- 1 --> 3
- 2 --> 2
- 3 --> 1

// Текст успеха

Наши помощники!

**КОНЕЦ КВИЗА**

Карточки

Разные ответы нужно распределить по категориям.
Каждая карточка относится к одной категории.
Фидбек к каждому ответу.
Не больше четырёх категорий.
Выглядит очень наглядным.
Подходит для небольшого круга вопросов.

На Платформе такой блок выглядит следующим образом:

В коде урока квизы-карточки имеют следующий формат: блок начинается с **КВИЗ (Карточки)**, затем следует описание задачи, далее идёт список, где элементы первого уровня определяют категории, по которым нужно будет распределять карточки, а элементы второго уровня обозначают ответы для этой категории. Блок заканчивается строкой **КОНЕЦ КВИЗА**.

**КВИЗ** (Карточки)

Расположите методы жизненного цикла фрагмента в подходящих группах.

- Методы ЖЦ объекта фрагмента

    - `onDestroy`
    - `onStop`
    - `onPause`
    - `onResume`
    - `onStart`
    - `onCreate`

- Методы ЖЦ `View` фрагмента

    - `onDestroyView`
    - `onViewCreated`
    - `onCreateView`

- Методы привязки фрагмента к `Activity`

    - `onDetach`
    - `onAttach`

**КОНЕЦ КВИЗА**

Сборная строка

Ответы нужно расположить в правильном порядке.
Общий фидбек.
Выглядит очень наглядным.
Ответы должны быть не очень длинными.

На Платформе такой блок выглядит следующим образом:

В коде урока квизы со сборной строкой имеют следующий формат: блок начинается с **КВИЗ (Сборная строка)**, затем следует описание задачи, далее идёт строчка вида // Список строк, после неё список, где все элементы расположены в правильном порядке. Далее следует строка // Текст успеха, и затем текст, который будет показываться в случае успеха или ошибки. Блок заканчивается строкой **КОНЕЦ КВИЗА**.

**КВИЗ** (Сборная строка)

Дополните код и составьте корректный запрос записи массива в `SharedPreferences`, где данные получаются
методом `getUsers`.

// Список строк

- `sharedPreferences.edit()`
- `putString(USER_LIST_KEY, Gson().toJSON(getUsers()))`
- `.apply()`

// Текст успеха

Ох уж этот код!

**КОНЕЦ КВИЗА**

Формат сниппетов

Блок, в котором студент тренируется в написании кода (и может его запустить), по ходу чтения урока.

Можно использовать для решения небольших задач, когда студент меняет код и проверяет результат. А так же, может посмотреть подсказки и авторское решение.

На Платформе такой блок выглядит следуюшим образом:

Или ещё:

Обратите внимание, что текстовое задание не является частью этого блока. Поэтому располагаем задание перед этим блоком (а не внутри).

Как выглядит текст успеха:

Так же можно использовать блок для запуска кода, если хотите, чтобы студент просто поигрался с кодом:

Для уменьшения кода в уроках, выносим сниппеты в отдельные файлы.

В коде урока

**СНИППЕТ** [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 в блоке с кодом нельзя вставлять другие блоки с кодом. Но подразумевается, что это единый документ.

Сниппет для решения небольших задач:

# НАЗВАНИЕ СНИППЕТА

## Прекод

val moneyAmmount = 0
// ...
moneyAmmount += 100_000_000_000
// ...  
println("Денег на вашем счёте: " + moneyAmmount)

## Подсказки

- В Kotlin два типа переменных: изменяемые `var` и неизменяемые `val`.
- В Kotlin переменные, указанные как целое значение и не превышающее максимальное для `Int`, автоматически будут
  определены как `Int`.
- Вы можете явно указать тип `Long`, добавив после значения переменной литеру `L`.

## Авторское решение

var moneyAmmount = 0L
moneyAmmount += 100_000_000_000
println("Денег на вашем счёте: " + moneyAmmount)

## Текст успеха

Ура, вы справились!

# НЕ ДЛЯ СТУДЕНТА !!!

- Если запускается и выводит текст, то всё окей.
- Если при запуске выводится "Val cannot be reassigned" - вывести ошибку "Нельзя изменить значение иммутабельной
  переменной".
- Если при запуске ошибка "Type mismatch: inferred type is Long but Int was expected" - вывести ошибку "Переменная типа
  Int не вместит в себя столь огромное число".

Формат тренажёра

В целом, всё аналогично сниппетам: делаем в отдельном файле. Но в отличии от сниппетов, условие задачи уже пишется в файле тренажёра, потому что по разметке так и получается, ведь тренажёр - это как будто отдельный урок.

На Платформе такой блок выглядит следуюшим образом:

Так выглядят подсказки:

Как выглядит текст успеха и ошибки (после нажатия на Проверить):

В коде урока

**ТРЕНАЖЁР** [Name of trainer](../code/trainers/02_numbers.md)

В файле с тренажёром

P.S. Тут тоже с разбиением на мини-блоки, но подразумевается, что это единый документ.

# Название тренажёра

## Задача

Джуниор разработчику Иннокентию 30 лет. Иннокентий попал в команду разработки приложения одного крупного банка, в его
команде есть программисты, возраст которых 25, 36, и 21 год. Какой средний возраст разработчика в команде Иннокентия?

- Объявите мутабельную переменную `averageAge`.
- Укажите возраст Иннокентия в качестве начального значения.
- В иммутабельную переменную `numberOfDevelopers` поместите количество разработчиков в команде.
- Вычислите средний возраст разработчика, полученное значение выведите на экран.

## Прекод

fun main() {
    // объявите мутабельную переменную averageAge со значением возраста Инокентия 30 лет
    // объявите иммутабельную переменную numberOfDevelopers с количеством разработчиков в команде

    // пересчитайте averageAge равную среднему возрасту (остальных участников 25, 36, и 21 лет)

    // выведите averageAge
}

## Подсказки

- для вычисления среднего возраста вам потребуется среднее арифметическое — сумма возрастов, поделённая на количество
  разработчиков в команде.

## Авторское решение

fun main() {
    var averageAge = 30
    val numberOfDevelopers = 4

    averageAge = (averageAge + 25 + 36 + 21) / numberOfDevelopers

    println(averageAge)
}

## Текст успеха

Прекрасно, Инокентий не так уж стар! 28 лет — отличный возраст для начала карьеры разработчика!

# НЕ ДЛЯ СТУДЕНТА !!!

- проверить, что объявлена как минимум 1 переменная `val`.
- проверить результат вывода = 28.

54 KiB Raw Permalink Blame History Unescape Escape

Код-стайл оформления кода уроков

Структура репозитория

Содержимое папок с уроками

Договорённости по названиям и форматам файлов

Оформление текста

Общее

Жирный шрифт

Код внутри строки

Блоки кода

Стандарты языков программирования

Изображения, видео, gif

Общее

Код-стайл

Особое выделение блоков на Платформе

Термин для глоссария

Блоки с цитатами

Блок пояснения

Блок-диалог

Блок-реплика

Блок-переход на следующий урок

Блок для скрытия/показа контента

Блоки-галереи

Блоки-квизы

Одиночный выбор

Множественный выбор

Выбор из списка

Текстовое поле

Квиз-макароны

Карточки

Сборная строка

Формат сниппетов

В коде урока

В файле со сниппетом

Формат тренажёра

В коде урока

В файле с тренажёром

54 KiB

Raw Permalink Blame History