Комментирование кода C, заголовка и исходных файлов
Я ищу "лучшую практику" для документирования своего кода на языке C. Как и в любом проекте, у меня есть некоторые заголовочные файлы ".h" и соответствующий исходный файл ".c"
В файле заголовка, какой комментарий вы вложили? А в исходных файлах?
Вопрос возникает потому, что, поскольку я хорошо комментировал свои заголовочные файлы, файлы c выглядят как беспорядок.
Какие ваши лучшие рекомендации по поддержанию кода хорошо прокомментированы?
Ответы
Ответ 1
Заголовок предназначен для пользователей кода. Поэтому я документирую интерфейс: как его использовать, предварительные условия и постусловия и т.д.
Файл .c предназначен для сопровождающих. Там я документирую реализацию: как все работает внутри, и почему они работают таким образом.
Ответ 2
Я предлагаю принять соглашения, наложенные таким инструментом, как Doxygen. Затем вместо комментариев кода вы также можете создавать документацию HTML/PDF/Latex и т.д., И это дает вам хорошие соглашения.
Согласитесь с Томасом о файлах cpp
Ответ 3
Для исходных файлов я предлагаю создать шаблон комментария для заголовка и заголовка функции.
В случае комментариев заголовка файла вы должны иметь краткое описание файла, имен функций, автора, даты создания и истории для записи изменений.
Включение заголовка функции, вы можете объяснить логику и назначение функции и различные параметры. Убедитесь, что любая сложная логика или отклонение от обычного поведения хорошо документированы с помощью комментариев.
Ответ 4
Если это персональный проект, я бы предположил, что существует множество стандартов кодирования, которые вы могли бы принять (почти все включают разделы на как выложить комментарии).
Если нет, я бы предположил, что ваша компания /teaam/project уже имеет что-то на месте, поэтому используйте это.