[sldev] Doxygen & Comments

Tateru Nino tateru.nino at gmail.com
Fri Jun 8 04:39:16 PDT 2007


Comments are there so you know what the code is *supposed* to do. The
code only tells you what it actually *does* ;)


Peter Rizla wrote:
>
> 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
>
>  
>
>
> ------------------------------------------------------------------------
> New Yahoo! Mail is the ultimate force in competitive emailing. Find
> out more at the Yahoo! Mail Championships
> <http://uk.rd.yahoo.com/mail/uk/taglines/default/championships/games/*http://uk.rd.yahoo.com/evt=44106/*http://mail.yahoo.net/uk/>.
> Plus: play games and win prizes.
> ------------------------------------------------------------------------
>
> _______________________________________________
> Click here to unsubscribe or manage your list subscription:
> /index.html
>   

-- 
Tateru Nino
http://dwellonit.blogspot.com/



More information about the SLDev mailing list