День 2348. #BestPractices
Пишем Хорошую Документацию. Окончание
Начало
Продолжение

8. Используйте современные инструменты (вне зависимости от API)
Существует множество инструментов, которые помогут вам эффективно и результативно создавать документацию:
- Генераторы статических сайтов (SSG): такие инструменты, как MkDocs, Docusaurus, Hugo, Jekyll и Sphinx, являются популярным выбором. Они берут простые файлы разметки (например, Markdown) и создают профессионально выглядящие веб-сайты документации, с возможностью поиска. Они часто поставляются с темами, плагинами для поиска, поддержкой управления версиями и хорошо согласуются с подходом «Документация-как-Код».
- Платформы документации: такие сервисы, как Read the Docs, GitBook или Confluence, предлагают решения со встроенными функциями для совместной работы, управления версиями и презентации.
Выбирайте инструменты, которые соответствуют вашему рабочему процессу, размеру команды и техническим требованиям.

9. Используйте ИИ (осторожно)
Искусственный интеллект проникает в документацию. Генератор документации ИИ может стать мощным помощником, но крайне важно понимать его сильные и слабые стороны.
Потенциальные преимущества
- Генерация шаблонов: ИИ может быстро генерировать первоначальные черновики описаний функций/методов на основе комментариев или сигнатур кода (например, блоков ///summary).
- Саммари: ИИ может обобщать длинные технические объяснения или сложные разделы кода.
- Проверки согласованности: ИИ может помочь выявить несоответствия в терминологии или стиле в больших наборах документации.
- Перевод: сервисы перевода на другие языки совершенствуются, хотя человеческая проверка по-прежнему необходима для технической точности.

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

10. Развивайте культуру документирования
Отличная документация обычно не является продуктом одного человека, работающего в изоляции. Для этого требуются командные усилия и культурный сдвиг:
- Интеграция в рабочий процесс: сделайте документацию частью определения «готово» для новых функций или изменений API. Выделяйте на неё время во время спринтов.
- Поощряйте вклад: сделайте так, чтобы всем разработчикам (а не только преданным писателям) было легко вносить исправления и улучшения. Снизьте барьер для входа (например, простое редактирование Markdown через Git).
- Признавайте и вознаграждайте: признавайте и цените усилия, которые вложены в создание и поддержание высококачественной документации.
- Показывайте пример: если руководители групп и старшие разработчики отдают приоритет документации, другие, скорее всего, последуют их примеру.

Итого
Создание документации, которая понравится разработчикам, — непростая задача, но это чрезвычайно ценная инвестиция. Красивые документы — точные, понятные, хорошо структурированные, простые в навигации и визуально приятные — напрямую влияют на производительность разработчиков, снижают нагрузку на поддержку, улучшают адаптацию и улучшают общее восприятие вашего ПО или платформы.

Источник: https://dev.to/therealmrmumba/beyond-code-how-to-create-beautiful-documentation-that-developers-actually-love-best-practices-hc4

День 2349. #SystemDesign101 #Шпаргалка
Коды Состояний HTTP

1xx: Информационные
100 Continue (продолжайте);
101 Switching Protocols (переключение протоколов);
102 Processing (идёт обработка);
103 Early Hints (предварительный ответ).

2xx: Успех
200 OK (хорошо);
201 Created (создано);
202 Accepted (принято);
204 No Content (нет содержимого);
205 Reset Content (сбросить содержимое);
206 Partial Content (частичное содержимое);
207 Multi-Status (многостатусный);
208 Already Reported (уже сообщалось).

3xx: Перенаправление
300 Multiple Choices (несколько вариантов);
301 Moved Permanently (перемещено навсегда);
302 Found (найдено);
303 See Other (смотреть другое);
304 Not Modified (не изменялось);
305 Use Proxy (использовать прокси);
307 Temporary Redirect (временное перенаправление);
308 Permanent Redirect (постоянное перенаправление).

4xx: Ошибка клиента
400 Bad Request (некорректный запрос);
401 Unauthorized (не авторизован);
402 Payment Required (необходима оплата);
403 Forbidden (запрещено);
404 Not Found (не найдено);
405 Method Not Allowed (метод не поддерживается);
406 Not Acceptable (неприемлемо);
407 Proxy Authentication Required (необходима аутентификация прокси);
408 Request Timeout (истекло время ожидания);
409 Conflict (конфликт);
410 Gone (удалён);
411 Length Required (необходима длина);
412 Precondition Failed (условие ложно);
413 Payload Too Large (полезная нагрузка слишком велика);
414 URI Too Long (URI слишком длинный);
415 Unsupported Media Type (неподдерживаемый тип данных);
416 Range Not Satisfiable (диапазон не достижим);
417 Expectation Failed (ожидание не оправдалось);
422 Unprocessable Entity (необрабатываемый экземпляр);
423 Locked (заблокировано);
424 Failed Dependency (невыполненная зависимость);
425 Too Early (слишком рано);
426 Upgrade Required (необходимо обновление);
428 Precondition Required (необходимо предусловие);
429 Too Many Requests (слишком много запросов);
431 Request Header Fields Too Large (поля заголовка запроса слишком большие);
449 Retry With (повторить с);
499 Client Closed Request (клиент закрыл соединение).

5xx: Ошибка сервера
500 Internal Server Error (внутренняя ошибка сервера);
501 Not Implemented (не реализовано);
502 Bad Gateway (ошибочный шлюз);
503 Service Unavailable (сервис недоступен);
504 Gateway Timeout (шлюз не отвечает);
505 HTTP Version Not Supported (версия HTTP не поддерживается);
506 Variant Also Negotiates (вариант тоже проводит согласование);
507 Insufficient Storage (переполнение хранилища);
508 Loop Detected (обнаружено бесконечное перенаправление);
509 Bandwidth Limit Exceeded (исчерпана пропускная ширина канала);
510 Not Extended (отсутствует расширение);
511 Network Authentication Required (требуется сетевая аутентификация);
520 Unknown Error (неизвестная ошибка);
521 Web Server Is Down (веб-сервер не работает);
522 Connection Timed Out (соединение не отвечает);
523 Origin Is Unreachable (источник недоступен);
524 A Timeout Occurred (время ожидания истекло);
525 SSL Handshake Failed (SSL-рукопожатие не удалось);
526 Invalid SSL Certificate (недействительный сертификат SSL).

Коды состояний, которые не должны были существовать
218 This Is Fine - Отсылка к мему, означает, что ошибка не должна перехватываться сервером и отправляться клиенту.
418 I’m A Teapot – Введен в 1998 году как первоапрельская шутка (4/1/8). Означает, что чайник не может сварить кофе.
420 Enhance Your Calm – Нестандартный ответ, предлагающий клиенту «остыть». Сейчас заменён кодом 429.
451 Unavailable For Legal Reasons – Доступ к ресурсу закрыт по юридическим причинам, например, по требованию органов государственной власти или по требованию правообладателя в случае нарушения авторских прав. Является отсылкой к роману Рэя Брэдбери «451 градус по Фаренгейту».
530 Site Frozen – Сайт работает, но заморожен провайдером (например, за неоплату).

Источники:
- https://github.com/ByteByteGoHq/system-design-101
- https://ru.wikipedia.org/wiki/Список_кодов_состояния_HTTP

День 2350. #ЗаметкиНаПолях
Разбираем Генераторы Исходного Кода. Начало
Генераторы исходного кода, представленные в C# 9, стали мощным инструментом для метапрограммирования в .NET, позволяя разработчикам генерировать дополнительный исходный код. Они запускаются во время компиляции для проверки кода и генерации дополнительных файлов кода C#. Затем эти файлы компилируются вместе с остальным кодом, что позволяет динамически создавать код на основе существующей кодовой базы. Генератор исходного кода можно использовать для различных целей, таких как скафолдинг, проверка и повышение читаемости и удобства обслуживания кода.

В C# 12 генераторы исходного кода получили дальнейшее развитие, позволяя реализовывать более сложные сценарии и повышая производительность за счёт сокращения шаблонного кода и улучшения проверок во время компиляции.
1. Инкрементные генераторы
Регенерируют код только при необходимости, что значительно повышает производительность. Кэшируют результаты предыдущих запусков и повторно генерируют код только при изменении базовых данных.

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

3. Улучшенная диагностика
Позволяет лучше сообщать об ошибках и предупреждениях непосредственно в сгенерированном коде. Разработчики получают чёткую обратную связь в процессе разработки, что упрощает отладку и поддержку сгенерированного кода.

4. Улучшения API Roslyn
Больше возможностей для анализа и изменения синтаксического дерева, позволяющих реализовывать более сложные сценарии генерации кода.

Простой генератор кода
1. Настройка проекта
Создадим проект библиотеки и добавим нужные NuGet-пакеты

dotnet new classlib -n MySourceGenerator
cd MySourceGenerator
dotnet add package Microsoft.CodeAnalysis.CSharp

2. Генератор кода
Понадобится класс, реализующий IIncrementalGenerator:

using System.Text;
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.Text;

[Generator]
public class HelloWorldGenerator : IIncrementalGenerator
{
  public void Initialize(
   IncrementalGeneratorInitializationContext context)
  {
    var src =
"""
using System;
namespace HelloGenerated;
public static class HelloWorld 
{
  public static void SayHello() 
   => Console.WriteLine("Hello from the generated code!"); 
}
""";

    context.RegisterPostInitializationOutput(
     ctx => ctx.AddSource(
      "HelloWorldGenerated",
      SourceText.From(src, Encoding.UTF8)));
  }
}

Этот простой генератор добавляет класс HelloWorld с методом SayHello в ваш проект. Сгенерированный код будет скомпилирован с остальной частью проекта, что позволит вызывать HelloWorldGenerated.HelloWorld.SayHello() из вашего кода.

3. Интеграция с проектом
Создадим консольный проект:

dotnet new console -n UseSourceGenerator

Добавим ссылку на проект генератора из другого проекта:

<ProjectReference Include="..\MySourceGenerator\MySourceGenerator.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />

Заметьте два нестандартных атрибута:
- OutputItemType="Analyzer" - позволяет целевому проекту просматривать указанный проект в качестве анализатора;
- ReferenceOutputAssembly="false" - гарантирует, что целевой проект не будет ссылаться на DLL генератора кода во время компиляции.

Теперь сгенерированный класс HelloWorld доступен в консольном проекте.

4. Сборка и запуск
Соберём проект и запустим его. Мы увидим в консоли вывод из сгенерированного метода HelloWorld.SayHello():

// Program.cs

HelloGenerated.HelloWorld.SayHello();

Окончание следует…

Источник: https://thecodeman.net/posts/source-generators-deep-dive

День 2351. #ЗаметкиНаПолях
Разбираем Генераторы Исходного Кода. Окончание
Начало

Чтение кода из файла
Если у вас есть код C# в файле, и вы хотите использовать этот код в для генерации дополнительного или изменения существующего кода, вы можете прочитать содержимое файла и использовать его как часть процесса генерации исходного кода.

Предположим, у есть файл MyClass.cs со следующим содержимым:

// MyClass.cs
namespace MyNamespace;
public class MyClass
{
  public void MyMethod()
  {
    // реализация метода
  }
}

В проекте генератора кода читаем содержимое этого файла и генерируем на его основе дополнительный код:

using System.Text;

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.Text;

[Generator]
public class FileBasedGenerator 
 : IIncrementalGenerator
{
  public void Initialize(
   IncrementalGeneratorInitializationContext context)
  {
    var srcFile = context
     .AdditionalTextsProvider
     .Where(f => f.Path.EndsWith("MyClass.cs"));

    var content = srcFile
     .Select((f, ct) => f.GetText(ct)?.ToString());

    // используем код из файла 
    // для генерации нового кода
  }
}

В клиентский проект нужно добавить файл MyClass.cs и ссылку на проект генератора кода, как показано в предыдущем посте.

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

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

3. Отладка и диагностика
Используйте расширенные возможности диагностики в C#12, чтобы предоставлять понятные сообщения об ошибках и предупреждения в генераторах исходного кода. Это поможет другим разработчикам понять и исправить проблемы, возникающие из-за сгенерированного кода.

4. Управление исходным кодом
Будьте осторожны при проверке сгенерированного кода в системе управления версиями. В большинстве случаев лучше повторно сгенерировать код во время процесса сборки, а не сохранять его в репозитории.

5. Версионирование
При обновлении генераторов кода убедитесь, что сгенерированный код остаётся совместимым с предыдущими версиями. Рассмотрите возможность предоставления путей миграции, если сгенерированный код значительно изменится.

Источник: https://thecodeman.net/posts/source-generators-deep-dive