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