Markdown, Learning, Giga

Markdown, Learning, Giga

https://giga.chat/link/gcsIbChixe

То есть Вы мне предлагате писать Описание кода, которое включает в себе и код и описательный текст просто в выбрав Markdown - и все будет работать?

1. Если это так напишите мне небольшую Памятку для этого действия. Какое расширение файла должно быть выбрано с смаого начала итд. То есть опишите весь процесс подробно.
2. Вы предложили мне писать Описание и Код в формате markdown потому что это у добно и принято в софтверной индустрии.
3. Писать описание кода и текста для меня всегда было сложно, потому что я не знаю как это надо делать. Как это делают в программной индустрии. Может быть есть какое-нибудь средство для написания в одном файле текста и кода.

1. Да, все верно. Использование Markdown — это стандарт де-факто в программной индустрии для написания документации, которая смешивает описательный текст и фрагменты кода. VSCode изначально создан для комфортной работы с этим форматом.

1. Памятка: как правильно настроить VSCode для описания архитектуры и кода

Шаг 1. Выбор расширения файла

• С самого начала сохраните ваш файл с расширением .md (например, Architecture.md или DesignDoc.md).
• Если вы создаете новый файл в VSCode (Ctrl+N), прежде чем начать писать, сразу нажмите Ctrl+S и сохраните его как имя.md. Это критически важно: пока у файла нет расширения или оно .txt, VSCode не знает, какие правила проверки к нему применять.

Шаг 2. Выбор языка (если VSCode ошибся) Если вы открыли старый файл или VSCode не распознал формат:

• Посмотрите в правый нижний угол окна VSCode. Там указан текущий язык (например, Plain Text).
• Кликните на него.
• В поиске начните вводить Markdown и выберите его.
• Если нужного языка нет, выберите Configure File Association for '...' и назначьте этот тип файлов языку Markdown навсегда.

Шаг 3. Как писать текст и код (синтаксис) Чтобы VSCode перестал подчеркивать слова волнистой линией, нужно явно указывать, где заканчивается текст и начинается код.

• Обычный текст: пишется как есть. Для заголовков используйте # (H1), ## (H2).
• Встроенный код (однострочники): если вы упоминаете название класса или метода внутри предложения, берите его в одиночные обратные кавычки: Trading.Gateway.
• Блоки кода (многострочные схемы и код): это главное правило. Оберните блок в тройные обратные кавычки ```.
  • Чтобы убрать красную подсветку внутри блока (если это не исполняемый код, а просто текст или псевдокод), после первых кавычек напишите text: ```text Trading.Web | v Trading.Gateway | +--> Trading.Api.Orders ```
  • Если это C# код, напишите csharp — тогда появится правильная подсветка синтаксиса: ```csharp public class OrderService { ... } ```

Шаг 4. Отключение лишних расширений (если линии остались) Если вы все сделали правильно, а красные линии не исчезли, скорее всего, их рисует линтер (например, markdownlint).

• Нажмите на проблемное слово.
• В появившейся лампочке (Quick Fix) выберите Disable line for 'markdownlint' или Disable rule 'no-multiple-blanks' for this project.
• Либо временно отключите расширение markdownlint в панели расширений (Ctrl+Shift+X), пока пишете черновик.

Шаг 5. Просмотр результата Нажмите Ctrl+Shift+V или Ctrl+K V, чтобы открыть окно предпросмотра Markdown. Там вы увидите чистый документ без служебных линий редактора.

2. Почему это принято в индустрии

В современной разработке принято правило «документация живет рядом с кодом» (Documentation as Code).

• Текстовые файлы .md можно положить в систему контроля версий (Git) вместе с самим кодом.
• При каждом изменении архитектуры разработчик меняет текст в том же коммите, что и код. Документация никогда не устаревает.
• Такие файлы легко превращаются в красивый сайт со справочником (например, с помощью генератора DocFX или MkDocs), где блоки кода будут аккуратно подсвечены.

3. Средства для написания текста и кода в одном файле

Помимо базового Markdown, в индустрии есть несколько подходов и инструментов для более сложной документации:

Инструменты, основанные на Markdown:

• Markdoc и MDX: расширения синтаксиса Markdown, которые позволяют вставлять полноценные компоненты (например, вкладки с разными языками кода, сворачиваемые блоки details). Популярны для написания современной технической документации.
• AsciiDoc: более мощный конкурент Markdown. Лучше справляется с очень большими документами, перекрестными ссылками и сложными таблицами. Поддерживается в VSCode через расширения.

Инструменты для визуализации архитектуры (внутри Markdown):

• PlantUML и Mermaid: это языки для рисования диаграмм обычным текстом. Вы пишете текст в блоке кода, а в предпросмотре видите готовую картинку. Пример Mermaid для вашей задачи: ```mermaid graph TD A[Trading.Web] --> B[Trading.Gateway] B --> C[Trading.Api.Orders] B --> D[Trading.Api.MarketData] ``` В VSCode для этого нужно установить расширение Markdown Preview Mermaid Support.

Pattern: Architectural Decision Records (ADR) Это стандарт индустрии для фиксации архитектурных решений. Создается папка docs/adr/, в которой каждый файл (например, 0001-use-microservices.md) содержит строгую структуру:

1. Контекст: какая была проблема.
2. Решение: что именно сделано (ваш текст про этапы 1–5).
3. Последствия: плюсы, минусы и технический долг. Это дисциплинирует описание и помогает новым разработчикам понять, почему система устроена именно так.

Инструменты для генерации документации из кода (Code-first):

• XML Documentation Comments (C#): вы пишете комментарии прямо над классами в коде, используя теги <summary>, <param>. Инструменты вроде DocFX или Sandcastle собирают их в единый красивый сайт. Подходит для описания API, но не для высокоуровневой архитектуры.
• Sphinx (с MyST): золотой стандарт в Python-мире, но часто используется и в C#-проектах. Позволяет писать сложный текст с математическими формулами и автоматически выкачивать описания из кода.
• Docusaurus: фреймворк от Meta (Facebook) для создания профессиональных сайтов с документацией, где Markdown-файлы превращаются в полноценное приложение с поиском и версиями.

Для вашей задачи (описание эволюции системы и примеров кода) обычного файла .md с блоками ```text``` и ```csharp``` будет более чем достаточно. Начните с него, а когда текста станет много, можно будет добавить Mermaid для схем и подумать о сборке простого сайта документации.