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 <[email protected]> > > > > > On Wed, Mar 9, 2011 at 17:31, Francesco Nwokeka < > > > > > > [email protected]> 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 _______________________________________________ KDE-Telepathy mailing list [email protected] https://mail.kde.org/mailman/listinfo/kde-telepathy
