[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
RE: [cdt-dev] typos and missing documentation in the CDT source code
|
Hi Chris,
It is nice to hear I'm not alone, and that something has started! If I get
it right, during peer reviews comments get added/clarified as well?
> I have probably lost more productivity over the last four years working
> on CDT due to trying to figure out someone else's undocumented code
> than I have anything else.
This is exactly what I meant... CDT could proceed faster if things were
better documented.
> However, documenting a piece of code means you have to understand it in
> the first place, so correcting the problem retroactively can be tough.
Yes, can be tough at places, but often even putting down trivial things
(like the general purpose of a class) may save hours to the reader...
Documentation could be added and refined gradually, and possible errors
(misunderstandings) could be fixed along the way, just as code bugs get
fixed. And notations like MBI (May Be Incorrect) may also help.
Hope we're getting somewhere :)
Andras
> -----Original Message-----
> From: cdt-dev-bounces@xxxxxxxxxxx [mailto:cdt-dev-bounces@xxxxxxxxxxx] On
> Behalf Of Chris Recoskie
> Sent: Friday, February 15, 2008 1:35 PM
> To: CDT General developers list.
> Subject: RE: [cdt-dev] typos and missing documentation in the CDT source
> code
>
> I agree with you 100%. I have probably lost more productivity over the
> last four years working on CDT due to trying to figure out someone else's
> undocumented code than I have anything else.
>
> However, documenting a piece of code means you have to understand it in
> the
> first place, so correcting the problem retroactively can be tough. FWIW,
> our team puts most of our code through peer review, which helps a lot up
> front.
>
> ===========================
>
> Chris Recoskie
> Team Lead, IBM CDT Team
> IBM Toronto
> http://www.eclipse.org/cdt
>
>
>
>
> "Andras Varga"
> <andras@omnetpp.o
> rg> To
> Sent by: "'CDT General developers list.'"
> cdt-dev-bounces@e <cdt-dev@xxxxxxxxxxx>
> clipse.org cc
>
> Subject
> 02/15/2008 06:20 RE: [cdt-dev] typos and missing
> AM documentation in the CDT source
> code
>
> Please respond to
> "CDT General
> developers list."
> <cdt-dev@eclipse.
> org>
>
>
>
>
>
>
> Hi all,
>
> It is nice to hear that typos in the API will be fixed.
>
> However, the question of missing Javadocs generated no replies at all. Do
> CDT developers feel comfortable with having to figure out the
> functionality
> and the intent behind a class or method from the [often messy] source code
> every time? OTOH if someone adds a new method or class, how long would it
> take to add a 3-line Javadoc to write down what it does...? Five minutes?
> Ten??
>
> Andras
>
>
> > -----Original Message-----
> > From: cdt-dev-bounces@xxxxxxxxxxx [mailto:cdt-dev-bounces@xxxxxxxxxxx]
> On
> > Behalf Of Schaefer, Doug
> > Sent: Friday, February 08, 2008 5:36 PM
> > To: CDT General developers list.
> > Subject: RE: [cdt-dev] typos and missing documentation in the CDT source
> > code
> >
> > See bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=210116
> >
> > Doug
> >
> > -----Original Message-----
> > From: cdt-dev-bounces@xxxxxxxxxxx [mailto:cdt-dev-bounces@xxxxxxxxxxx]
> > On Behalf Of Andras Varga
> > Sent: Friday, February 08, 2008 5:55 AM
> > To: 'CDT General developers list.'
> > Subject: [cdt-dev] typos and missing documentation in the CDT source
> > code
> >
> > Hi all,
> >
> > Some questions about the state of the CDT source code.
> >
> > There are several typos in class names and method names:
> > EnvirinmentVariable, BuildSustem, etc. I believe they're collected in
> > bug # 210116. Are they going to be fixed for 5.0, or are they going to
> > stay in the name of backwards compatibility? They look kinda dodgy.
> >
> > Second: most classes in CDT are almost totally undocumented. No Javadoc
> > comments, or any kind of useful comments at all. I can't believe this is
> > not a problem even for CDT contributors themselves. This was raised as
> > bug #214324, then closed out of frustration. Any comments on this?
> >
> > Best regards,
> > Andras
> >
> > _______________________________________________
> > cdt-dev mailing list
> > cdt-dev@xxxxxxxxxxx
> > https://dev.eclipse.org/mailman/listinfo/cdt-dev
> > _______________________________________________
> > cdt-dev mailing list
> > cdt-dev@xxxxxxxxxxx
> > https://dev.eclipse.org/mailman/listinfo/cdt-dev
>
> _______________________________________________
> cdt-dev mailing list
> cdt-dev@xxxxxxxxxxx
> https://dev.eclipse.org/mailman/listinfo/cdt-dev
>
>
> _______________________________________________
> cdt-dev mailing list
> cdt-dev@xxxxxxxxxxx
> https://dev.eclipse.org/mailman/listinfo/cdt-dev
