В постах очень часто затрагиваю тему орфографии текстовых фрагментов переменных в коде программы, но проверка орфографии комментариев так же важна.
Часто комментарии пишутся для внутреннего использования, и орфографические ошибки в них считаются не критичными, так как клиент их не увидит.
Но даже в случае "закрытого кода", когда код программ не доступен клиентам, ошибки из комментариев могут попасть в документацию по API-функциям программы, которая, как правило, генерируется из специально оформленных комментариев, и клиенты смогут
оценить грамотность (или неграмотность) программистов.
Популярными форматами документирования кода для формирования документации являются JavaDoc, XMLDoc и ряд других.
Программа "Локализатор исходного кода" написана на MS Visual Basic и использует оформление комментариев XMLDoc, которое позволяет получать интерактивные подсказки при написании кода по функциям и их параметрам.
Для формирования документации по коду проекта используется SandCastle.
Далее приведены скриншоты созданной документации (из chm-файла).
Список функций одного из классов:
Фрагмент документации по функции Add из приведенного выше списка:
Пример кода для документирования функции GetGenerateUnique:
''' <summary>
''' Генерирует уникальное слово для сравнения в словаре
''' </summary>
''' <param name="in_value">слово</param>
''' <param name="in_ctxt">контекст</param>
''' <returns>уникальное слово</returns>
''' <remarks></remarks>
Public Function GetGenerateUnique _
(ByVal in_value As String, ByVal in_ctxt As String) As String
Фрагмент документации сформированной по описанию в комментариях к GetGenerateUnique:
Внутренняя документация полезна не только самим программистам, но и необходима при передачи ее на аудит/исправление/использование другим разработчикам,
в том числе пользователям, если есть доступ к функциям программы через API.
Примечание: в дальнейшем, возможно, часть функций будет переведена в библиотеки и доступна через API.
Полезные ссылки к статье:
См. пост Проверка орфографии в исходном коде проекта
Часто комментарии пишутся для внутреннего использования, и орфографические ошибки в них считаются не критичными, так как клиент их не увидит.
Но даже в случае "закрытого кода", когда код программ не доступен клиентам, ошибки из комментариев могут попасть в документацию по API-функциям программы, которая, как правило, генерируется из специально оформленных комментариев, и клиенты смогут
оценить грамотность (или неграмотность) программистов.
Популярными форматами документирования кода для формирования документации являются JavaDoc, XMLDoc и ряд других.
Программа "Локализатор исходного кода" написана на MS Visual Basic и использует оформление комментариев XMLDoc, которое позволяет получать интерактивные подсказки при написании кода по функциям и их параметрам.
Для формирования документации по коду проекта используется SandCastle.
Далее приведены скриншоты созданной документации (из chm-файла).
Список функций одного из классов:
Фрагмент документации по функции Add из приведенного выше списка:
Пример кода для документирования функции GetGenerateUnique:
''' <summary>
''' Генерирует уникальное слово для сравнения в словаре
''' </summary>
''' <param name="in_value">слово</param>
''' <param name="in_ctxt">контекст</param>
''' <returns>уникальное слово</returns>
''' <remarks></remarks>
Public Function GetGenerateUnique _
(ByVal in_value As String, ByVal in_ctxt As String) As String
Фрагмент документации сформированной по описанию в комментариях к GetGenerateUnique:
Внутренняя документация полезна не только самим программистам, но и необходима при передачи ее на аудит/исправление/использование другим разработчикам,
в том числе пользователям, если есть доступ к функциям программы через API.
Примечание: в дальнейшем, возможно, часть функций будет переведена в библиотеки и доступна через API.
Полезные ссылки к статье:
- Sandcastle - http://ru.wikipedia.org/wiki/Sandcastle
- Практическое руководство. Создание XML-документации в Visual Basic - http://msdn.microsoft.com/ru-ru/library/xzysab5k.aspx
- Генератор документации - http://ru.wikipedia.org/wiki/Генератор_документации
См. пост Проверка орфографии в исходном коде проекта
Комментариев нет:
Отправить комментарий