PDA

View Full Version : Code comments



zlatko
8th February 2006, 13:55
HI all!

Is it good programing style comented class methods in *.h and *.cpp? Or better only in *.h or only in *.cpp?
I like before every method available in *.cpp write some block with info about this method. But then i must copy the same info in *.h ?

Any propposition?:)

KjellKod
8th February 2006, 14:24
I believe it is the most common to comment, explain in the declaration of a function i.e. the .h file.

Also; it is much easier to get an overview of a class if you can read about what the functions does in the .h file.

Alternatively, if you have the function, abstract, explanation in the .cpp file it would be harder to get an overview over the whole class since the comments are not standing out as much (due to the amount of code)...

--- Note: It's good programming practice to have comments in .cpp as well, explaining in the code what is being done at specific steps can seriously help one to read and understand what the code does.

Did I help or only confuse?

Codepoet
8th February 2006, 15:07
I have two types of comments:
In the header explaining what a method does, parameters, return value... Later doxygen will generate from these comments a nice documentation.
The other type of comments explains code passages: What I am doing here, sometimes why I'm doing something that way and not the obvious way... These comments help me to understand my own code when I have to read it again some days, months or even years later.
But try to avoid writing how you are doing something - most of the time reading the code is better.

yop
8th February 2006, 16:13
You could check out:
http://www.cprogramming.com/tutorial/comments.html
http://dkrukovsky.blogspot.com/2005/07/how-to-write-comments.html
and my favourite
http://thc.org/root/phun/unmaintain.html :p

Codepoet
8th February 2006, 16:18
http://thc.org/root/phun/unmaintain.html :p
The most important one :D

zlatko
8th February 2006, 16:44
ok...
thanks for mooore information but my question is neverless actual :rolleyes:

Where better comment the method ?

1) in *.h
2) in *.cpp
3) 1) and 2)

for your replies i see that first choice is better...then when anybody will be research in my code he must always switch betwwen *.h(for look for comments) and *.cpp(for look for implementation)...:confused:

zlatko
8th February 2006, 16:45
The most important one :D
yes i think too;)

Codepoet
8th February 2006, 17:32
ok...
thanks for mooore information but my question is neverless actual :rolleyes:

Where better comment the method ?

1) in *.h
2) in *.cpp
3) 1) and 2)

for your replies i see that first choice is better...then when anybody will be research in my code he must always switch betwwen *.h(for look for comments) and *.cpp(for look for implementation)...:confused:
I can't tell you what is better, but that my approach works very good for me: Users of my code never read the implementation. They want to know how to use my methods. That's header only. And editors / IDEs can display the comments as little popup windows while writing code ;)
A maintainer probably already knows how to use the method and jumps directly to the implementation to fix it which should be easier with the comments there which describe what you did.

yop
8th February 2006, 19:25
I can't tell you what is better, but that my approach works very good for me: Users of my code never read the implementation. They want to know how to use my methods. That's header only. And editors / IDEs can display the comments as little popup windows while writing code ;)
A maintainer probably already knows how to use the method and jumps directly to the implementation to fix it which should be easier with the comments there which describe what you did.
So I'd say that it depends on the final product. If you 're writing a library that other devs will use (probably in a binary form) then writing the comments in the header files (and in doxygen format) is better. If you are writing code that will be maintained / reviewed many times you should go with the comments in the cpp file. Anyway, out of habbit I guess, in my final (beta and up) releases I have doxygen style comments in almost all of my header files.

zlatko
9th February 2006, 09:27
Ok guys Big thanks)

I use doxygen so my final decision is :
*.h - input only brief description for class methods
*.cpp - input detailed description

I think this method wiil be readability for users and for developers:rolleyes: