Подход комментирования: Как комментировать то, что используется в приложении?

Question

Мое приложение IVR содержит много глобальных переменных, что является побочным эффектом неизбежной инфраструктуры, предоставляемой поставщиком. Таким образом, во многих случаях переменной присваивается значение в одном JSP, и к ней не прикасаются снова, пока вызывающая сторона не войдет в приложение через несколько диалогов.

Когда мне нужно добавить или изменить такую ​​переменную, я оставляю комментарий к преамбуле, описывающий эту модификацию, не вдаваясь в подробности всей функциональности:

<%--IVRAvenger 20100927 Issue#:12345: Keep track of what the caller entered.  Used for multiple ID/ID change logic, further on. --%>
<assign name="gblIDInput" expr="memberID"/>

Это вводит в заблуждение? Было бы лучше просто добавить эти небольшие операторы и позволить другим разработчикам сканировать код модуля, в котором эти переменные применяют свою (сомнительную) магию?

Спасибо
IVR Avenger

Answer 1

При такой проблеме я бы порекомендовал внешний словарь, в котором перечислены глобальные переменные, назначение и типичные рабочие процессы, связанные с ними.

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

Если вы реализуете такой документ, я бы также порекомендовал любые общие шаблоны или принципы, которые воплощены в коде. Включая известные плохие выборы и то, почему они были плохими, не повредит. Поскольку большинство разработчиков не будут читать (и, конечно, поддерживать) такой документ, вы пишете для нового сотрудника, которому была предоставлена ​​документация в качестве задачи, или для будущего сопровождающего, который, наконец, разочаровался настолько, что фактически прочитал документацию. *