[sldev] Doxygen & Comments

[Dzonatas]

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

--