Документор кода или псевдокод

Осенью 2016 года сотрудникам, рекламирующим и распространяющим продукт ClearSQL, мной было предложено позиционировать его не только для разработчиков, но и для тестировщиков. Но пользу утилит аудиторов кода они оценили только недавно, начав серию статей с Псевдокода (https://www.youtube.com/watch?v=pFCAALkJ9RU).
Именно Псевдокод является самым простым и доступным способом оценки полноты и качества кода. Фактически, это комментарии к коду, понятные любому человеку.
Комментарии псевдокода добавляются в основной код со специальными тегами. За счёт этих тегов можно вычленять только комментарии (обычный текст, который можно брать из текста технического задания от аналитика продукта) или композицию комментариев со строками кода. В ClearSQL есть возможность генерить Flowchart (блок-схему, UML диаграмму) по комментариям псевдокода. Нижеследующие скриншоты сняты из редакторов кода, псевдокода и диаграмм приложения ClearSQL 6.9.
Текст кода с комментариями псевдокода:

Диаграмма flowchart кода:

Текст псевдокода:

Диаграмма flowchart по комментариям псевдокода (UML формат, слева-направо, со строками кода):

Если аналитики балуют программистов составлением тех.задания в виде блок-схем, то сравнение UML диаграммы от аналитика с Flowchart по комментариям псевдокода даст моментально объём тех.задания, не покрытого кодом или не продуманного аналитиком. В нижеследующем примере видно, что программист обработал не только граничные значения (есть/нет звонок), но и промежуточный результат (абонент занят).
Блок-схема аналитика (нарисовано вручную в Paint):

Диаграмма flowchart по комментариям псевдокода со строками кода:


Программистам, ленящимся писать комменты к коду, нет смысла тратить время и способности сочинителя обычных текстов, потому что можно сначала вставить в пустой скрипт текст от аналитика

закомментировать эти строки (можно с тэгами псевдокода)

разбить их на логические куски

и уже к имеющемуся плану скрипта дописывать код
.
По-сути, просто "тупокодить". А сколько при этом экономится общекомандного времени на разработку!

Наличие комментариев в коде имеет ряд преимуществ:
* из-за текучки кадров следующему программисту будет быстрее и проще разобраться с чужим кодом (легаси);
* maintainability index (уровень качества кода) любого кода достигается больше минимума в 85 за счёт 3/10 комментированных строк (но только если это не временно неиспользуемый код, а именно пояснения к коду = полезные комментарии);
* по комментариям к коду не только легче разобраться с его предназначением, но и можно улучшить свои знания языка программирования;
* наличие комментариев в коде ускоряют восстановление истории задачи и добавляют уверенности при смене или потере VCS и BTS, так как нет смысла искать изменения по системе контроля версий или по баг-трекинговой системе;
* сертификация программного обеспечения подразумевает наличие документации, которую легко и быстро можно вычленить из комментариев псевдокода, а не писать с нуля, как это было в моей практике.

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