- Для позначення відступу використовуйте 4 пробілу поспіль
- Використовуйте пробіли, а не табуляцію!
- Оголошуйте по одній змінної в рядку.
- Уникайте, якщо це можливо, коротких і заплутаних назв змінних (Наприклад: "a", "rbarr", "nughdeget").
- Односимвольні імена змінних підходять тільки для ітераторів циклів, невеликого локального контексту і тимчасових змінних. В інших випадках ім'я змінної повинно відображати її призначення.
- Заводите змінні тільки в міру необхідності.
- Функції та змінні повинні іменуватися з великої літери, а якщо ім'я змінної або функції складається з декількох слів, то перше слово має починатися з великої літери, інші - з малої.
- Уникайте абревіатур
- Імена класів завжди починаються з великої літери.
- Використовуйте порожні рядки для логічної угруповання операторів, де це можливо.
- Завжди використовуйте один порожній рядок як роздільник
- Завжди використовуйте один пробіл перед фігурною дужкою
- Завжди ставте один пробіл після '*' або '', якщо вони стоять перед описом типів. Але ніколи не ставте пробіли після '*' або '' і ім'ям змінної.
- Бінарні операції відокремлюються пробілами з 2-х строн.
- Після перетворення типів не ставте пробілів.
- Уникайте перетворення типів в стилі C.
Фігурні дужки
- Візьміть за основу розстановку відкривають фігурних дужок на одному рядку з виразом, з яким вони передують
- Виняток: Тіло функції і опис класу завжди відкривається фігурною дужкою, що стоїть на новому рядку
- Використовуйте фігурні дужки в умовах, якщо тіло умови в розмірі перевищує одну лінію, або тіло умови достатню складне і виділення дужками дійсно необхідно
- Виняток 1: Використовуйте дужки, якщо батьківське вираз складається з декількох рядків / обгорток
- Виняток 2: Використовуйте фігурні дужки, коли тіла розгалужень if-then-else займають кілька рядків
- Використовуйте фігурні дужки для позначення порожнього тіла умови
Круглі дужки
- Використовуйте круглі дужки для угруповання виразів:
Використання конструкції switch
розрив рядків
- Довжина рядка коду не повинна перевищувати 80 символів. Якщо треба - використовуйте розрив рядка.
- Коми поміщаються в кінець розірваної лінії; оператори поміщаються в початок нового рядка. Залежно від використовуваної вами IDE, оператор на кінці розірваної рядки можна прогледіти.
Спадкування і ключове слово virtual
- При перевизначенні virtual-методу, не пишіть слово virtual в заголовки.
Як цим користуватися
Як згенерувати html
Ви тільки що створили файл з документацією.
Створення файлу налаштувань
Коли ви тільки створили файл з документацією, треба створити файл - сховище налаштувань. Для цього
редагування Doxyfile
Якщо треба, відредагувати Doxyfile
- або F4
- або утилітою з графічним інтерфейсом - для цього в командному рядку
генерація документації
Після цього запустити створення документації
- або з командного рядка командою:
- або утилітою з графічним інтерфейсом по кнопочки, схожою на шестірню - для цього в командному рядку
Ви хочете оновити документацію для файлу, у якого вона вже є, але застаріла. У командному рядку (в тому каталозі, де лежить Doxyfile):
Зауваження з оформлення документації
Документувати слід класи, члени класів і функції з усіма параметрами. Крім того, для окремих модулів в цілому слід документувати, як ними користуватися.
документування класів
документування функцій
документування модулів
У будь-якому місці коду
різні штуки
- Текст на головній сторінці - @mainpage
- Створення нової сторінки - @page ідентифікатор назву
Наприклад @page pagereq Вимоги до системи
- Створення секції - @section ідентифікатор назву
Наприклад @section common Загальні вимоги
- Вставка прикладу коду - @code
Цей тег парний, його закриває @endcode
- Короткий опис - @brief
Можна налаштувати файл опцій таким чином, щоб в короткий опис виносилося перше речення до точки докладного опису (за замовчуванням опис вважається докладним). Для цього потрібно включити опцію JAVADOC_AUTOBRIEF - в утиліті doxywizard вона знаходиться на першій сторінці.
Після цього група в дужках @<… @> Наприклад, таким чином можна групувати методи класу:
- Не бійтеся порушувати описані вище правила, якщо вам здається, що вони тільки заплутають ваш код.