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

[Nicholaz Beresford]

IMHO not.

Usually what gets buried in the source code is
needed exactly then when the source code is
looked at anyway.

If of those 30 persons every one puts into the
source code that which is not obvious from looking
at the code itself, you'll have a readable program.

Usually, in my experience, when you put notes
and codes in different places, what you get quite
quickly are two things entirely out of sync.


Phoenix wrote:
 > * 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

Of all those, I'd only need the 2nd part.


Nick


Second Life from the inside out:
http://nicholaz-beresford.blogspot.com/


Chance Unknown wrote:
> 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.