A simple request from a simple guy

[Martin Klapetek]

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'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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.kde.org/pipermail/kde-telepathy/attachments/20110310/83d23e17/attachment.htm