Глава 5

Соглашения об именах и комментариях

Все мы прекрасно знаем, сколь важны подробные комментарии для документирования исходного текста и насколько удобнее и доступнее для понимания делают его вразумительные имена. Но кто из нас не воздвигал в пылу вдохновения новые функции и целые новые классы, усеянные объявлениями переменных типа int x или char *p без единого словечка комментариев? Все это хозяйство превосходно и безошибочно работает и в таком виде переходит в новые версии ваших продуктов, постепенно начисто вылетая у вас из головы.

Где-нибудь через полгода, когда очередная версия начинает трещать по швам, вам приходится вспомнить о существовании такой функции. Вы долго смотрите на нее, снова и снова спрашивая себя: "О чем же я тогда думал?" Вы тратите несколько часов только на то, чтобы понять, как же работает этот собственноручно вами написанный фрагмент. А представьте себе, какие выражения припасет для вас программист из соседнего отдела, вынужденный постигать замысловатый ход ваших мыслей! Чтобы помочь вам избежать подобных ситуаций, в этой главе излагаются некоторые несложные общие соглашения об именах и комментариях.

Здесь вы познакомитесь со следующими темами:

• Правила комментирования исходного текста на C++, включая исходные и заголовочные файлы, функции-члены, переменные и т. д.

• Актуализация ваших комментариев

• Расшифровка венгерской нотации и ее место в соглашениях об именовании

• Некоторые альтернативы венгерской нотации

• Самодокументирование исходного текста путем разумного выбора имен