A simple request from a simple guy

[David Edmundson]

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.

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
>> KDE-Telepathy at kde.org
>> https://mail.kde.org/mailman/listinfo/kde-telepathy
>>
>
>
> _______________________________________________
> KDE-Telepathy mailing list
> KDE-Telepathy at kde.org
> https://mail.kde.org/mailman/listinfo/kde-telepathy
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.kde.org/pipermail/kde-telepathy/attachments/20110310/c35f8685/attachment.htm