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

Question

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

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

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

Answer 1

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

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

Answer 2

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

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

Answer 3

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

согласен с Томасом о CPP файлы

Answer 4

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

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

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