«Локализатор исходного кода» предназначен для локализации программных продуктов путем изменения их исходных кодов без предварительной подготовки.
Программа может быть использована при разработке программного обеспечения на серверах сборки, для автоматической локализации исходного кода, но она может также применяться и на рабочих компьютерах пользователей для проверки орфографии в исходных кодах, текстовых файлах, буфере обмена и словарях переводов.
Специальная версия программы позволяет проводить обфускацию исходного кода.


 

четверг, 12 декабря 2013 г.

Необходимость проверки орфографии в комментариях для внутренней документации на примере XMLDoc и программы "Локализатор исходного кода"

В постах очень часто затрагиваю тему орфографии текстовых фрагментов переменных в коде программы, но проверка орфографии комментариев так же важна.

Часто комментарии пишутся для внутреннего использования, и орфографические ошибки в них считаются не критичными, так как клиент их не увидит.
Но даже в случае "закрытого кода", когда код программ не доступен клиентам, ошибки из комментариев могут попасть в документацию по 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.

Полезные ссылки к статье:


См. пост Проверка орфографии в исходном коде проекта

Комментариев нет:

Отправить комментарий