Комментирование кода C, заголовка и исходных файлов

Я ищу "лучшую практику" для документирования своего кода на языке C. Как и в любом проекте, у меня есть некоторые заголовочные файлы ".h" и соответствующий исходный файл ".c"

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

Какие ваши лучшие рекомендации по поддержанию кода хорошо прокомментированы?

ОТВЕТЫ

Ответ 1

Заголовок предназначен для пользователей кода. Поэтому я документирую интерфейс: как его использовать, предварительные условия и постусловия и т.д.

Файл .c предназначен для сопровождающих. Там я документирую реализацию: как все работает внутри, и почему они работают таким образом.

Ответ 2

Я предлагаю принять соглашения, наложенные таким инструментом, как Doxygen. Затем вместо комментариев кода вы также можете создавать документацию HTML/PDF/Latex и т.д., И это дает вам хорошие соглашения.

Согласитесь с Томасом о файлах cpp

Ответ 3

Для исходных файлов я предлагаю создать шаблон комментария для заголовка и заголовка функции.

В случае комментариев заголовка файла вы должны иметь краткое описание файла, имен функций, автора, даты создания и истории для записи изменений.

Включение заголовка функции, вы можете объяснить логику и назначение функции и различные параметры. Убедитесь, что любая сложная логика или отклонение от обычного поведения хорошо документированы с помощью комментариев.

Ответ 4

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

Если нет, я бы предположил, что ваша компания /teaam/project уже имеет что-то на месте, поэтому используйте это.