[sldev] Doxygen & Comments

[Peter Rizla]

IMAO: The ability to insert comments was not made a part of source code files just so a company could claim ownership of some generic/bespoke code, nor to big up the author of said piece of code. They were created so that a noob to it could soon follow and understand the code without much hard study. And to know where to go if there is a problem with (a bit of) the code or their clarity in understanding it (in both senses). 
 
Nicholaz Beresford wrote:
> 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.

Jason Giglio wrote:
> One of the major principles of good language and program design is 
> that
> related things should be close to each other in the file and application.

John Hurliman wrote:
> While we are talking about experiences I will throw mine in. When
> contracted to write software for international teams I've always been 
> asked to go the extra mile on software comments and documentation,

************************************
IMAO: Those are things that can be thought of as some golden rules.
Do they not teach them anymore? Is it just anarchic rebellion? Or laziness?
It is fair enough, and we have almost certainly all done it, rules can be broken. Especially behind closed doors. That does not necessarily make it right. Certainly if you were to break social rules out in the open, you will have trouble from it. It is also all too easy to fall foul of the rules when you are ignorant of them, or if they are unclear to you. Especially when you are among those rules that do not follow an obvious logic. Ignorance is of course, often regarded as no defence.

I'd rather jump onto a bus that goes to where I wanna go, or read a map of the route, than try to follow the road signs or landmarks as, if and when I see them. Sure enough, so that I can know exactly where I am along the journey the next time I go, I will be taking note of those road signs and landmarks as I travel this time.

Dzonatas wrote:
> 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

************************************
I don't think they are saying that, and I guess you are being a bit sarcastic.
I think its better to not use slang, write cryptic or irrelevant comments, just to use plain and simple English.
English, because LL talks (American) English.
 
Dzonatas wrote:
> 
> 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 

************************************
I'm sorry but my externally hyperlinked comment on this cannot be accessed because I have decided to re-arrange things, or it was removed to another location during the archiving process. And I all but repeated others.

Dzonatas wrote:
> 
> 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?
************************************
Check with the author if I can find them? (darn, his name was excluded by the coding standards)
Highlight this code vs comment mismatch in discussion with the community/developers?
Jump to a conclusion by doing one of your choices ? - because you think you have a bigger one than everyone else


		
___________________________________________________________ 
Now you can scan emails quickly with a reading pane. Get the new Yahoo! Mail. http://uk.docs.yahoo.com/nowyoucan.html
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.secondlife.com/pipermail/sldev/attachments/20070608/169e6e01/attachment.htm