Commenting C code, header and source files [closed]

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 4 years ago.

Improve this qu开发者_如何学JAVAestion

I'm looking for a "best practice" to document my C code. Like in any project I have some header files ".h" and the respective source file ".c"

In the header file what kind of comment you put in? And in source files? The question arise up because since I commented well my header files, the c files looks like a mess.

What's your best practices in keeping the code well commented?

---

The header is meant for users of the code. So in there I document the interface: how to use it, preconditions and postconditions, etcetera.

The .c file is for maintainers. In there, I document the implementation: how things work internally, and why they work that way.

---

I suggest adopting the conventions imposed by a tool like Doxygen. Then instead of just code comments, you can also generate HTML/PDF/Latex etc documentation and its gives you good conventions.

Agree with Thomas about the cpp files

---

If this is a personal project I'd suggest there are plenty of coding standards out there you could adopt (almost all include sections on how to lay out comments).

If not, I would imagine your company / teaam / project already has something in place so use that.

---

For source files I suggest you create a comment template for File Header and Function Header.

In case of File Header Comments, you should have a brief description of the file, function names, author, date of creation and history to record modifications.

Incase of function header, you can explain the logic and purpose of the function and various parameters. Please ensure that any complex logic or deviation from common behaviour is well documented through comments.