[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