Hosting Doxygen docs (Re: [sldev] Doxygen & Comments)

[Chance Unknown]

IMHO

Comments in the source are beneficial only when they conform to a style
guide for the type of information included. If its just an academic bunch of
notes to make clear the selection of algorithm: then its far better to
document on a wiki for other people to look at, and not include in the
source code. If you get a 30 person team all stuffing notes into source
code, it becomes a maintenance nightmare, it hides the code, and it makes
the algorithms very difficult to see.

STYLE GUIDE : KNOW IT, BREATHE IT, LIVE IT.

Usually, whatever gets buried into source code should be of use to everyone,
and not hide algorithms or language constructs because of the verbosity.
Notes do much better in an attached text file within a project that has many
participants. A team usually will read the notes once or twice, and then
know what it is that they are looking at in the source code. If you deposit
those notes physically into the source, then you make it something a team
collectively now has to page past in order to get to the algorithm. That
wastes everybodys time.

---

On 6/7/07, Rob Lanphier <robla at lindenlab.com> wrote:
>
> Hi all,
>
> On a tangent, if you all would like us to host a set of
> Doxygen-generated comments, let us know, specifically by filing a task
> in JIRA in the WEB project.  Since I'm a little fuzzy on where I'd put
> said comments, I'm not sure when I'd personally get around to doing it,
> but a JIRA task would be a handy reminder to get around to it.
>
> Thanks
> Rob
>
> On 6/7/07 9:48 AM, Phoenix wrote:
> > Regardless of international consumers of the code, the majority of
> > english speaking devs that work on SL would benefit from:
> >
> > * comments in headers which describe
> > ** parameters
> > ** valid parameter ranges
> > ** if parameter ranges are checked
> > ** return value
> > * comments in code which describe
> > ** why a tricky and non-obvious is not written for clarity
> > ** what a tricky and non-obvious tangle of code does
> >
> >
> > On 2007 Jun 7, at 09:17, Dzonatas wrote:
> >> Max Okumoto wrote:
> >>> Would patches which add javadoc type comments to functions be
> >>> welcome?  I usually add comments to code that I am trying to
> >>> understand.
> >>
> >> The main problem with comments in code is that the comments are
> >> usually in some sub-human form of English. The prose of the sub-human
> >> language is insignificant to on the scale of readability and
> >> communicative expression of the content it relates to the reader, or,
> >> better yet, to the programmer. What matters more to the programmer is
> >> the ability to communicate that content of that comment to the
> >> intended audience. If the programmer desires to only to deal with an
> >> audience that is able to read at least some form of sub-human
> >> English, the comments will be written in that so stated English form.
> >> The global world is much greater and diverse, and there are many
> >> programmers that can barely translate English. The comments may be of
> >> some interest to them, but it may be more of a pain in the ass in
> >> their time to comprehend it than it is just to look straight at the
> >> code. Also, there are more programmers out there that do not speak
> >> any form of English. Those comments that are written in a form of
> >> English are of no use to a programmer that does not speak any form of
> >> English. In fact, the comments appear more like litter on the road
> >> where you have to go pay some state or province tax to clean-up,
> >> which such taxs funds are usually channeled through endless reams of
> >> political red-tape until it ends up in the paycheck of a law
> >> enforcement officer to watch over a community work project of less
> >> fortunate group of sub-humans to complete the road service clean-up
> job.
> >>
> >> I could get into a debate over the amount of time is wasted in
> >> comments, which are pieces of the source that have absolutely no
> >> function to the end-user. There are obviously far better tools to
> >> document source than in-line liter. Some of the most simplest issue
> >> trackers make a better basis for a documentative system. If a
> >> programmer thinks there is a need to create further documentation for
> >> a class, then that programmer has done well to follow-up with a
> >> tracker item for such reason and where such documentation will flow.
> >> Do not take this mixture of documentation and tracker issue as the
> >> only way or as the way that I suggest is best, as it is merely better
> >> idea to give a programmer the fluidity to work focused on the code
> >> itself than for that programmer to worry about foreign, sub-human
> >> comments.
> >>
> >> Being able to program is like a fluid degree of skill at a foreign
> >> language or any language, really. Skill with a program language
> >> profoundly compares to skill with a foreign language. Does anybody
> >> tell professional English writers that they must comment their books
> >> and articles with C++? I didn't think so.
> >>
> >> Dz
> >>
> >> --
> >> _______________________________________________
> >> Click here to unsubscribe or manage your list subscription:
> >> /index.html
> >
> > ------------------------------------------------------------------------
> >
> > _______________________________________________
> > Click here to unsubscribe or manage your list subscription:
> > /index.html
> >
>
>
>
> _______________________________________________
> Click here to unsubscribe or manage your list subscription:
> /index.html
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.secondlife.com/pipermail/sldev/attachments/20070607/795543c5/attachment.htm