[Lazarus] "show declaration hints" has more power in it than is really used

[Bernd]

2010/7/23 Martin <lazarus at mfriebe.de>:
> On a first glance, if the source is to complicated to explain tiself, the
> you need comments.
> But actually, then you need to clean up your source, so it becames readable
> again.
>
> Of course readable, is defined on the readers ability, and that varies =>

It depends what the reader knows about the internal architecture of
the program and what is obvious to him but to nobody else.

> but then for the more experienced reader any comment explaining the obvious
> "to him" just is in the way of the big picture.

No. This is simply not true. Comments in the code are not for
yourself, because then you would not have to write any comments since
*you* already know how it works. Comments are for *other* people who
might later read your code and don't yet know how it works. I cannot
believe that we are seriously discussing the helpfulness or necessity
of comments and that there could be any doubt about it. Of course
comments are *always* helpful! There simply is no reason to leave them
away, unless you intentionally want nobody else to ever read or
understand the code.

How can a comment ever be in the way? If it tells you nothing new you
simply ignore it. We are talking about small comment blocks at the
method headers. How can 2 or 3 light green lines *above* a procedure
definition or above the class definition come into your way while you
are working *inside* the procedure body?

> So comment will always be a conflict of interest => unless they can be
> hidden => but that forces everyone to use an editor with the hide-function,
> rather than their personal choice....

fpdoc forces everybody who wants to read the code to use Lazarus
because otherwise half of the code is missing ("half of the code"
meaning the comments that IMHO are substantial part of any readable
code).