Rivalry2

HTML Diff

0 added 0 removed

Original 2026-01-01

Modified 2026-02-21

1 <a>#Руководства</a>

2 <ul><li>30 сен 2019</li>

3 <li>0</li>

4 </ul>Рано или поздно в жизни каждого разработчика наступает момент, когда он не понимает, как работает его код. Выясняем, что с этим делать.

5 vlada_maestro / shutterstock

6 Пишет о программировании, в свободное время создаёт игры. Мечтает открыть свою студию и выпускать ламповые RPG.

7 Программисты часто сталкиваются с тем, что не могут прочитать код. Такое случается постоянно: когда только приходят в новый проект, когда проверяют код коллеги или - так бывает чаще всего - когда смотрят результат своей же работы. Чтобы этого избежать, нужно писать и читать документацию.

8 Содержание

9 <ul><li><a>Два вида документации</a></li>

10 <li><a>Правила хорошего тона в составлении документации</a></li>

11 <li><a>Где писать документацию в C#</a></li>

12 <li><a>Как создать файл документации</a></li>

13 <li><a>Заключение</a></li>

14 </ul>Разработчики имеют дело с двумя основными видами документации:

15 <ol><li>Пользовательская документация. Это руководство по эксплуатации программ. Обычно оно нужно для сложных профессиональных инструментов. Если же пользователи не могут сами разобраться в приложении пиццерии, то лучше доработать интерфейс - добровольно никто инструкцию читать не станет.</li>

16 <li>Техническая документация. Это пояснения для программистов, которые будут использовать или дорабатывать существующий код. Они помогут быстро вникнуть в проект и начать работать. Или же продолжить писать программу после долгого перерыва.</li>

17 </ol>К сожалению, не все разработчики (практически никто) любят читать документацию. Любителей писать её и того меньше. Однако делать это очень важно, потому что сложно поддерживать проект без документации.

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

19 1. Документация нужна не всегда

20 Если программа одноразовая, не стоит тратить время на написание пояснений. Например, если нужен небольшой скрипт, который будет написан за пять минут и использован 1-2 раза.

21 2. Документация нужна не везде

22 Также не нужно писать пояснения ко всему. Если код написан хорошо, то по названиям уже будет понятно, что это такое и зачем оно используется. Например, легко догадаться, что методint Sum (int a, int b)возвращает результат сложения двух чисел.

23 Исключение можно сделать, если речь идет об API или фреймворке, которыми пользуются многие разработчики: они не всегда видят исходный код, но могут использовать классы и методы. Поэтому им важно иметь список доступных методов. В этом случае задокументировать всё нужно просто для галочки.

24 3. Документация должна быть точной

25 Очень важно уметь ясно выражать свои мысли. Нужно предельно точно описывать, что делает тот или иной фрагмент кода. Для этого стоит давать как можно более короткие определения. Например:

26 /// <summary> /// Сообщение в чате. /// </summary> class Message { … /// <summary> /// Текст сообщения. /// </summary> public string Text { get { return this.text; } } }В этом фрагменте кода объем документации к классу и его свойству не превышает одного предложения. Этого достаточно, чтобы было понятно, что это такое и для чего его нужно использовать.

27 4. Документация должна быть сухой

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

29 5. В документации не должно быть старого кода

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

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

32 Если есть сомнения пригодится ли еще этот код, его лучше сохранить в системе контроля версий - именно для этого ее и придумали.

33 Дальше речь пойдет о том, как писать техническую документацию для программ на C#. Вся работа будет вестись в Visual Studio.

34 Вариантов много. Например, можно сделать это в Word или Google Docs, тогда разработчики смогут скачивать файл из интернета. Некоторые хранят инструкции в печатном виде, но это плохой вариант, потому что документация быстро устаревает.

35 Лучший способ - писать всё прямо в коде программы. Тогда у каждого разработчика будет доступ к документации в любое время. Самый примитивный вариант - использовать комментарии.

36 В C# есть два вида комментариев. Однострочные:

37 int a = 11 + 12; //Это однострочный комментарийИ многострочные:

38 /* Начало комментария Это Многострочный Комментарий Конец комментария */Компилятор во время сборки игнорирует комментарии и просто вырезает их, поэтому на работу программы они не влияют.

39 Более продвинутый вариант - использовать XML. Чтобы вставить XML-комментарий, нужно перед названием класса, поля, свойства или метода поставить тройной слеш.

40 После этого автоматически будет создано два элемента:

41 <ol><li>Summary - общий комментарий. В нем пишут, что делает метод или для чего нужен класс.</li>

42 <li>Param - комментарий об аргументе. В нем указывается, какое значение надо передать.</li>

43 </ol>Практически все инструменты, в том числе и Visual Studio, поддерживают вывод подсказок, которые подгружаются из документации. И теперь, если навести на методMain ()или его аргумент, то можно увидеть, что было написано в комментарии.

44 Такой способ намного лучше, потому что человеку вообще не нужно ничего открывать, чтобы определить, что делает какой-нибудь фрагмент кода. Конечно, наличие XML создает визуальный шум, но его можно просто скрыть.

45 Еще можно использовать такие XML-элементы, как:

46 <ul><li>Returns - возвращаемое значение;</li>

47 <li>Value - значение свойства;</li>

48 <li>Exception - исключение;</li>

49 <li>Remarks - ремарка к основному комментарию.</li>

50 </ul>Таких элементов очень много, подробнее почитать о них можно в <a>документации Microsoft</a>. Цель же этой статьи - показать, как документировать код, чтобы разбираться в проекте стало легче, а не сложнее.

51 Иногда все-таки нужно сохранить документацию вне кода. Чаще всего ее сохраняют в HTML-формате, а потом загружают на сайт, чтобы разработчики имели к ней доступ.

52 Для этого сначала нужно зайти в настройки проекта:

53 А потом перейти во вкладкуBuildи поставить галочкуXML documentation file:

54 Теперь вместе с компиляцией программы будет создаваться файл с документацией в формате XML. Его можно преобразовать в HTML с помощью специальных утилит. Microsoft для этого рекомендует использовать<a>DocFX</a>или<a>Sandcastle</a>.

55 Рассмотрим на примере DocFX. Его можно скачать с помощью NuGet Package Manager в Visual Studio. Для этого нажмите на проект правой кнопкой мыши и выберите пунктManage NuGet Packages:

56 Затем перейдите во вкладкуBrowseи введите в поле поиска названиеdocfx.console, а потом нажмитеInstall:

57 После нужно подтвердить установку и согласиться с условиями лицензионного соглашения.

58 Теперь при сборке проекта будет создаваться папка_site, в которой находится сайт с документацией. Однако это касается классаProgram, поэтому чтобы проверить работу DocFX, нужно добавить какой-нибудь класс:

59 namespace ConsoleApp1 { /// <summary> /// Класс, который представляет пользователя. /// </summary> public class User { private string name; /// <summary> /// Конструктор класса. /// </summary> /// <param name="name">Имя пользователя.</param> public User(string name) { this.name = name; } /// <summary> /// Меняет имя пользователя. /// </summary> /// <param name="name">Имя пользователя.</param> public void ChangeName(string name) { this.name = name; } /// <summary> /// Метод для вывода имени пользователя. /// </summary> /// <returns>Возвращает имя пользователя.</returns> public string GetName() { return this.name; } } }После компиляции проекта с таким классом можно проверить сайт. Его главная страница будет пуста - она нужна для того, чтобы вкратце описать свою программу. Сама же документация находится по адресуapi/index.html.

60 Вот как она выглядит:

61 Многим, и мне в том их числе, гораздо интереснее писать код, а не описывать его. Однако хорошая документация очень важна, если над проектом работает несколько человек или если это API, которым будут пользоваться сторонние программисты.

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

63 <a>Бесплатный курс по Python ➞Мини-курс для новичков и для опытных кодеров. 4 крутых проекта в портфолио, живое общение со спикером. Кликните и узнайте, чему можно научиться на курсе. Смотреть программу</a>