[sldev] Doxygen & Comments

[Phoenix]

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 186 bytes
Desc: This is a digitally signed message part
Url : http://lists.secondlife.com/pipermail/sldev/attachments/20070607/5d0e5694/PGP.pgp