Вопросы личного характера

1.Какой из встречавшихся вам кодов был лучше всего документирован? В чем были его особенности?

a.Было ли у этого кода много внешних спецификаций? Многие ли из них вы прочли? Можно ли быть уверенным, что вы достаточно знаете о коде, вовсе не прочтя их?

b.В какой, по вашему мнению, мере качество этой документации было обязано личному стилю программирования автора, а в какой – тре бованиям и наставлениям той организации, в которой он работал?

Если код хорошо документирован, отдельные документы с описанием необязательны. Хорошее документирование достигается с помощью правильных имен, разделения на логические модули, применения простых технологий, четкого форматирования, регистрации предпо% ложений и толковых комментариев. Фирменный стиль полезен, но не заменяет умного и тонкого программирования. Если человек идиот, то он может написать отвратительный код даже при соблюдении самых строгих правил.

2.Если вы программируете на разных языках, различаются ли ваши стратегии составления документации для каждого из них?

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

3.Каким образом вы выделили важные фрагменты в последнем коде, который писали? Постарались ли сделать малозаметной закрытую информацию?

Внимательно отнеситесь к этому вопросу – естественно говорить себе, что ты написал хороший код. Но посмотрите на него так, будто его ав% тор – кто%то другой. Отнеситесь к нему критически.

4.Если вы работаете над кодом в составе группы, часто ли ее участники обращаются к вам с просьбой пояснить работу вашего кода? Смогли бы вы избавиться от таких отвлечений путем лучшего документирова ния кода?

Хорошее решение этой проблемы включает в себя два пункта:

a.Если вопрос действительно касается какого%то неясного места в ва% шем коде, то, разъяснив его спрашивающему (и уточнив, что в дей%

ствительности он хотел знать), задокументируйте каким%то спосо%