A simple request from a simple guy

[Arno Rehn]

On Thursday 10 March 2011 17:00:47 David Edmundson wrote:
> 2011/3/10 Martin Klapetek <martin.klapetek at gmail.com>
> 
> > On Wed, Mar 9, 2011 at 17:31, Francesco Nwokeka <
> > 
> > francesco.nwokeka at gmail.com> wrote:
> >> Hello to all devs!
> >> 
> >>        I'm new to telepathy so let me introduce myself. I'm an
> >> 
> >> anglo-italian( can you say that? )
> >> student from Italy and I'm currently finishing my studies at the
> >> university of Padova ( software
> >> developer ).
> >> I'm writing to tell you about a problem that doesn't affect me alone,
> >> but all those people who want
> >> to contribute to a project that's already started and quite big.
> >> 
> >> This problem is getting to know the code. The eyes of a new contributor
> >> are different from those of
> >> the devs who started the project. We "new ones" have to get to know how
> >> the data is handled, which
> >> classes do what and so on. This problem can be avoided with well
> >> commented code. Even little things
> >> help so that instead of reading the whole function, you can eaisily tell
> >> what a certain function
> >> does by simply reading its comment.
> > 
> > Fair enough. The question is, where should be the method comments? I'd
> > vote for the .cpp file, because sometimes I just want to open the header
> > file and have a quick look at what methods it provide, in this case, the
> > comments are getting in the way.
> > 
> > What do you think? Comment methods in implementation and the important
> > rest, which is only in header, comment in header (enums etc).
> > 
> > Marty
> 
> I would advocate:
>  How to use a function in the .h file (at the declaration)
>  How a function works in the .cpp file (at the definition)
> 
> I think that's how most people do it.
Agreed. This is also what most IDE's expect. KDevelop4 for example can show 
docs in a tooltip if they're included in the headers. This doesn't work with 
Qt for example, where the complete docs are in the .cpp files and you have to 
download a seperate package to get them.

-- 
Arno Rehn
arno at arnorehn.de