A simple request from a simple guy

[Francesco Nwokeka]

On Thursday 10 March 2011 17:08:53 Arno Rehn wrote:
> 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.

Yeah, it's what i sort of had in mind. In the .h file a short description on how to use the function 
and then in the .cpp ( on hard/non-trivial parts ) the description of what happens with the code.

Francesco