put comments in h or cpp files?
Author
Ive been noticing that when im writing code, i kind of just stick comments where ever i am when i think of them. So when i come accross a function that i forget what it does, sometimes the description is in the header file, and sometimes it is in the cpp file. I can think of reasons to put them in either place, but you certainly wouldnt want to have them in both, because it would be a maintenance nightmare. Right?
comments in header file: PROS
-this is the one spot where all functions are listed in a nice tidy location, and it kinda makes sense to have their descriptions here as well
comments in header file: CONS
-similar to above; this is supposed to be a nice tidy spot for the list of functions. They whole list would normally probably all fit on one page, but if you have 3 or 4 lines of comments for each one, it gets big and hard to scan down quickly when your trying to see if this class has a certain function
comments in cpp files: PROS
-this is where the implementation for functions is, so it makes sense for the descriptions to be handy too, so you can compare them. One thing i like to do when writing a new function is to write the description (comment) first, and then write the code. that way i can keep referring to the description and not get off track in the code.
comments in cpp files: cons
-when you want to know what a class does, you look in the header file, not the cpp file, so that would make sense to have the comments in the header
What do people think about this? Im trying to decide what makes the most sense, so i can stick to it and get used to it.
thanks!
I think the comments in the cpp file would be more useful. Hopefully the names of your functions would be descriptive enough that you don''t need a full blown comment descpription of each one. If a function name isn''t clear enough, you may want to consider renaming it, or just biting down and commenting it anyway..
Just my opinion on the matter, now I''m off to bed.
Just my opinion on the matter, now I''m off to bed.
I have a nasty tendency to litter my code with comments also, but normally I keep most of the descriptive things in the header file. ... A non-commented header file just does not look right.
A source code editor that can fold can make each function''s comments amount to but a single line when the fold is closed. (so you end up with 2 lines per function usually). This pretty much eliminates the CON of putting the documentation in the header file, imho. For what it is worth, I personally use VIM (vim.sf.net).
Another thought is to use a source code documentation tool to supplement the documentation. FWIW, I like doxygen (www.doxygen.org).
Now why I''ve been know to make comments for functions in the source file is it is often easier to find the top of the function rather than the entry in the header file. Important to me when I''m trying to remember what I wanted to say about a bug or a todo or some-such entry. Course, I could just write a script to put my cursor in the appropriate place now couldn''t I? So perhaps I don''t have a good excuse to clutter the source file after all...
Your mileage will vary no doubt
Luck,
Feral
A source code editor that can fold can make each function''s comments amount to but a single line when the fold is closed. (so you end up with 2 lines per function usually). This pretty much eliminates the CON of putting the documentation in the header file, imho. For what it is worth, I personally use VIM (vim.sf.net).
Another thought is to use a source code documentation tool to supplement the documentation. FWIW, I like doxygen (www.doxygen.org).
Now why I''ve been know to make comments for functions in the source file is it is often easier to find the top of the function rather than the entry in the header file. Important to me when I''m trying to remember what I wanted to say about a bug or a todo or some-such entry. Course, I could just write a script to put my cursor in the appropriate place now couldn''t I? So perhaps I don''t have a good excuse to clutter the source file after all...
Your mileage will vary no doubt
Luck,
Feral
i''m putting them in my sourcecode into the .H file - because i use doxygen for sourcecode generation; this is a very good way i think - at the first moment i was also sceptic, but it''s really good.
yep, i also recently started using doxygen and i really like it.
right now i put a brief description ( ///< abcxy ) next to variables and function declarations in the header, as well as full class description comments, while i put the longer function comments with parameter/return value descitptions in the .cpp file above each function implementation.
works really nice so far.
and i can really only recommend doxygen...especially if you download the dot tool it gets really cool when it produces UML diagrams for your classes and call graphs for your functions
right now i put a brief description ( ///< abcxy ) next to variables and function declarations in the header, as well as full class description comments, while i put the longer function comments with parameter/return value descitptions in the .cpp file above each function implementation.
works really nice so far.
and i can really only recommend doxygen...especially if you download the dot tool it gets really cool when it produces UML diagrams for your classes and call graphs for your functions
You must ask yourself one question: For whom are the comments intended for?
If you answer "the user of the class" then you should put the comments in the header file.
If you answer "the developer of the class" then you should put the comments in the implementation file.
[How To Ask Questions|STL Programmer''s Guide|Bjarne FAQ|C++ FAQ Lite|C++ Reference|MSDN]
If you answer "the user of the class" then you should put the comments in the header file.
If you answer "the developer of the class" then you should put the comments in the implementation file.
[How To Ask Questions|STL Programmer''s Guide|Bjarne FAQ|C++ FAQ Lite|C++ Reference|MSDN]
quote:Original post by dalleboy
You must ask yourself one question: For whom are the comments intended for?
If you answer "the user of the class" then you should put the comments in the header file.
If you answer "the developer of the class" then you should put the comments in the implementation file.
Smart guy right here, listen to him
. If you comment the source file only, and distrubute it as a library, there are no comments for the people actually using the library + header (outside of documentation). I like to put small comments in the header file describing what variables and stuff are used for and more descriptive comments about how things work, what exactly is going on, etc.
Yup, do what dalleboy says.
In the headerfile, explain what the functions do and how you should use the return value.
In the sourcefile, explain how the functions and algorithms work...
That''s what I do.
In the headerfile, explain what the functions do and how you should use the return value.
In the sourcefile, explain how the functions and algorithms work...
That''s what I do.
I agree also, What I tend to do is similar.
I generally put all the documentation comments that Doxygen would process in the header file: THis is the stuff the client will see after all so it should be the comments that describe the function\members\structures etc in terms of what it does, parameters, typical usage etc but nothing to indicate *its* implementation details
All implementation detail in the cpp file and commented in a way that doxygen doesnt process, the comments in the cpp files I think like mentioned before should shed light on how its implemented and as support to the internal developers rather then the client - especially true if you releasing code in libraries or object code.
With this you get consistent structure and html\latex (or all the options doxygen supports) format documented source code as a bonus.
[edited by - PantherBoy on July 26, 2003 12:16:19 PM]
I generally put all the documentation comments that Doxygen would process in the header file: THis is the stuff the client will see after all so it should be the comments that describe the function\members\structures etc in terms of what it does, parameters, typical usage etc but nothing to indicate *its* implementation details
All implementation detail in the cpp file and commented in a way that doxygen doesnt process, the comments in the cpp files I think like mentioned before should shed light on how its implemented and as support to the internal developers rather then the client - especially true if you releasing code in libraries or object code.
With this you get consistent structure and html\latex (or all the options doxygen supports) format documented source code as a bonus.
[edited by - PantherBoy on July 26, 2003 12:16:19 PM]
I am also going to put in a good word for doxygen.
In the header file, I put a brief (single line) comment for every item saying what the item is. In the source file, I put the bulk of the description including @param, @note, @warn, @sa, etc. Doxygen combines these into a nice reference.
In the header file, I put a brief (single line) comment for every item saying what the item is. In the source file, I put the bulk of the description including @param, @note, @warn, @sa, etc. Doxygen combines these into a nice reference.
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement
