#1С

Недавно в @Unofficial1C была дискуссия насчет полезности комментариев в коде и я высказался, что мой опыт заставляет к комментариям относиться с большим недоверием и надеяться на них в последнюю очередь.

Аргумент очевиден: разработчики забывают обновлять комментарии.

Я тогда поленился приводить примеры из типовых, а сегодня мне один начинающий в 1С коллега обратился с очередным WTF (в оригинале вопрос был "Как это использовать?" - см. картинку ниже) и я вспомнил то обсуждение.

Как теперь с этим жить?

Когда есть легаси API, которое нужно вызвать из своего кода, а с документацией "что-то не то":

1. Забыть про комментарии, как источник информации (если они устарели, они будут дезинформировать - пример на скриншоте ниже отлично это иллюстрирует).

2. Читать примеры клиентского кода (имею в виду код, который вызывает процедуру/функцию, информация по которой вам нужна). На этом этапе на исследуемый метод смотрим как на "черный ящик". В идеальном мире нужный клиентский код находится в юнит-тестах (xUnitFor1C) или в реализации сценариев поведения (Vanessa Behavior), но, к сожалению, наш мир очень далек от идеального.

К счастью, даже самый невнятный клиентский код можно посмотреть в отладчике, чтобы понять, какие параметры (тип, примеры значений) передавать и какой результат метод вернет.

3. Читать реализацию метода, если что-то из клиентского кода не очевидно. Опять же, не без помощи отладчика.

Когда написал код и возникло желание написать к нему комментарий:

1. Написать юнит-тест (в идеале - написать сценарий поведения и реализовать шаги по его автоматической проверке); гуглите: xUnitFor1C, Vanessa Behavior, Тестер 1С;

2. Выполнить рефакторинг кода таким образом, чтобы минимизировать необходимость каких-либо дополнительных пояснений.