[sldev] Doxygen & Comments

Nicholaz Beresford nicholaz at blueflash.cc
Thu Jun 7 12:26:02 PDT 2007


C++ as a language of expression clearly has it's
benefits and I agree that readable code (which most likely
also will use real world language to clarify, i.e. a
variable will be named particle_count rather than x32)
is preferrable over comment.

But where a real life language has benefits is describing
the why and what.  Here are two examples of recent patches
(or stuff I'm working on):


+   // vary view limit depending on usage.  view_limit determines the quota an emitter
+   // may generate: 100% generation a 0-meters distance, 0% generation at a distance of
+   // view_limit-meters (or more)  and proportional quotas in between (based on distance)
+   // (with a view_limit of draw_dist*4 the most distant visible (at draw_distance) source could
+   // generate at a quota of 75%)
+   view_limit = view_limit_low + (1.f - usage) * (view_limit_high - view_limit_low);



+   {
+       // simple quota computation based on distance to camera
+
+       // (normally this would start from 1.f (100%) but this gives
+       // nearer particles extra leeway, i.e. make the filter not cut
+       // in from the first meter)
+       pass_quota = 1.1f - dist_cam / view_limit;
+
+   }


I think both those comments belong to the place where a fellow
coder would look at the code, trying to understand what it does
(or fixing a bug) and the English would be very hard to be
substituted by an algorithmic language.


Nick


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


Dzonatas wrote:
> By no means is that meant negative, but it simply a reflection. In my 
> experience, C++ is a way to speak with a diverse population of 
> programmers even when there is no common non-program language for which 
> the two programmers may use to effectively communicate. I merely suggest 
> an accelerated means by reasonably attempt to pave the way on beautiful 
> virtual roads with nice lush un-littered scenic green grassy fields.
> 
> If their is to be commented source code, then those comments are best 
> put in another database. The reference number can be left in the source 
> code. That is justifiable, example:



More information about the SLDev mailing list