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. Dave > >> I'm not telling off anybody because I'm in no position to do so, but I >> think it would ease things for >> everyone because once telepathy becomes really-big and it's code is not >> well commented, i doubt new >> contributers will find their way easily around the project. >> For what I know that's the major problem when starting to patch new code >> for an open source project. >> >> So please don't be offended by this mail, it's just my opinion and as I >> already said, i'm not writing >> to tell anyone off, but to make a suggestion that in my opinion can make >> life easier for everyone :) >> >> Cheers, >> Francesco Nwokeka >> _______________________________________________ >> KDE-Telepathy mailing list >> [email protected] >> https://mail.kde.org/mailman/listinfo/kde-telepathy >> > > > _______________________________________________ > KDE-Telepathy mailing list > [email protected] > https://mail.kde.org/mailman/listinfo/kde-telepathy > >
_______________________________________________ KDE-Telepathy mailing list [email protected] https://mail.kde.org/mailman/listinfo/kde-telepathy
