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