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.
-- Arno Rehn [email protected] _______________________________________________ KDE-Telepathy mailing list [email protected] https://mail.kde.org/mailman/listinfo/kde-telepathy
