[sldev] Doxygen & Comments

[Dzonatas]

In the same regards, you are telling me that the majority of C++ 
programmers will benefit from:

* comments on English words in source code, which describe,
** common grammar of the English word
** appropriate usage of such English word in a prescribed context
** the expected perception of others when such word is used
* and further describe
** why such words should one have one meaning, as intended, if possible
** a justification of a to be rewritten usage of words that have lasted 
to this date because, solely, it has gone way beyond the scope of its 
original usage to the point a simple look-up into a thesaurus can't even 
justify the time to further beautify it in the context it exists

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:

// SLC++1234
class theCamelCaseClassName
{
    void someMethod();
...
}

boom! Reference SLC++1234 if you want the English context of it, which 
could be linked further to translations of that class written into other 
spoken languages, which Phoenix started to type in the previous message. 
I bet the entanglement, good and bad, becomes a bit easier to understand 
across the board at that point, especially (mush less) for those that do 
not speak English and (more so) for those that do not read C++ at all. =)

When push comes to shove (I mean to shove a release out to ship), is 
there a need to immediately re-write a piece of code to the intention 
that the comment says it is suppose to do, or would it be better just to 
delete the comment because the code that exists has gone through tried 
and tested means and an expert in C++ can translate exactly what it does 
for you?

Well, I don't want to waste just anybody's time anymore on my suggestion.

Second Life kicks ass! Let's build worlds! =)

Dz

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
>

--