| # Памятка по стилю статей (по текстам автора на mql5.com)
|
|
|
| Составлена по полным текстам статей 19946, 19623 и 21323 и по фрагментам
|
| 14026, 15294, 19804, 19852. Служит ориентиром при подготовке новых частей
|
| цикла. Это описание, а не образец для копирования: цитаты ниже короткие.
|
|
|
| ## Структура статьи
|
|
|
| 1. **Введение.** Подробный пересказ предыдущей части («В предыдущей части мы
|
| заложили фундамент…»), затем что будет сделано сейчас.
|
| 2. **«Намечаем путь».** Что нужно решить и в каком порядке, без кода.
|
| 3. **Шаги реализации.** Короткие заголовки из 2–4 слов («Новый маршрут»,
|
| «Схема работы с модулем», «Подопытные счета»).
|
| 4. **«Тестирование».** Как выглядит результат, со скриншотами («Рис. 1.»).
|
| 5. **«Заключение».** Что сделано и что дальше; последняя строка:
|
| «Спасибо за внимание и до новых встреч!»
|
| 6. **«Предупреждение»** (если уместно) и **«Содержание архива»** (таблица
|
| файлов с версиями и описанием).
|
|
|
| Оглавление в начале статьи нужно: сайт его сам не строит, пишется вручную
|
| (простой список заголовков). Пересобирать после каждой правки структуры.
|
|
|
| ## Голос и ритм
|
|
|
| - Авторское «мы» вместе с читателем: «приступим», «давайте посмотрим»,
|
| «сохраним изменения в файле…». «Я» почти не бывает.
|
| - Безличные обороты: «можно», «нужно», «стоит», «достаточно указать».
|
| - Предложения средней и большой длины, с уточнениями через запятую и тире.
|
| Короткие фразы только как переходы или выводы: «Но обо всём по порядку.»,
|
| «Описание класса готово.», «Возможно, это неспроста.»
|
| - Связки: «Итак», «Поэтому», «Однако», «Таким образом», «Кстати», «Теперь».
|
| - Иногда вопрос, на который тут же даётся ответ.
|
|
|
| ## Смягчение
|
|
|
| Частые слова и обороты: «вряд ли», «скорее всего», «в принципе», «по сути»,
|
| «довольно», «пока что», «вполне допустимо», «примерно», «судя по всему».
|
| Категоричные утверждения оставляем для установленных фактов (например,
|
| для поведения функции по документации).
|
|
|
| ## Как объясняются решения
|
|
|
| Сначала проблема или ограничение, затем решение, затем оценка альтернатив.
|
| Мотив проговаривается: «на это есть вполне понятная причина», «так как».
|
| Об ограничениях и неудачах пишется спокойно («К сожалению, на момент написания
|
| установить модуль не удалось…», «в справке прямо не указано…»).
|
|
|
| ## Оформление
|
|
|
| - Основное содержимое абзацами. Маркированные списки редки; если есть, то
|
| короткие, с вводной фразой и двоеточием.
|
| - Жирный шрифт почти не используется; термины и имена файлов выделяются
|
| курсивом или моноширинным шрифтом.
|
| - Код блоками, комментарии в коде русские и по возможности нумерованные
|
| («# 1. Импорт модуля»).
|
| - В MQL5 комментарии перед блоком начинаются с `//---`. На первом уровне тела
|
| функции они идут от левого края, на вложенных — по отступу описываемого блока.
|
| Комментарии `//` в конце строк выравниваются по колонке. У функций и обработчиков
|
| нужны непустые заголовки-рамки `//+---...---+` с названием или описанием.
|
| - Ссылки на предыдущие части с номерами и гиперссылками: «в части 3»,
|
| «как мы делали совсем недавно».
|
|
|
| ## Чего избегать в нашем черновике
|
|
|
| - Драматизации («коварная ошибка», «Важная оговорка», «Проговорим сразу»).
|
| - Длинных списков с жирными заголовками пунктов.
|
| - Уверенных формулировок там, где мы что-то не измеряли или не проверяли
|
| в документации.
|
Yuriy Bykov
3ab7e53a4f