[lazarus] Comments

[jozsef at wingchun.hu]

> > I'm sure there is the "WHY" poeple do not use comments. I do not know it
> > and I am curious.
>
...
> Arguments like 'the code is self documenting' just do not wash.
>
> Ian
--------
I mean when I read comments and function names I understand it.

> Maybe writing good, useful comments is more difficult than writing code...
Ok, it is your why. (Just in case you really don't use.)

> At least most of the times, when I write a piece of code I don't know what
> to add to it in comments, except the plain obvious like:
> function TUnitList.GetItem(Index: integer): TUnit;
> The function GetItem returns a Unit from the UnitList. It has one
parameter
> Index, which is the index of the unit in the list of the returned unit.
Sure. It is obvious and the names tell all the story.
It can happen TUnitList is not so obvious name (eg. an abbreviation).
Or not only get an item. Like pop and push in a stack. Do not stuck in my
example, please. The proc or func has side effects.

> Also it is not immediately clear if some comment is good, usefull. Code is
> checked by the compiler and by tests to see if it works. For comments
there
> is no such simple checking mechanism.
Well, if a person knows other people will read his code I don't think he
will
write stupidity. He should know what his code does. Even if he has some
mistake
it may better than no comments at all. Maybe you will se this: 'I think there
is
an inconsistency in comment and code here: ...'
And? There are other bugs too. :)
-------

> In general, I agree with Vincent that comments are often unneeded for a
> lot of procedures and would simply get in the way.  However, whenever
> there are confusing algorithms they should be commented.  At least one
> comment to explain a group of procedures would have been a good idea.
I like it.

Joe