Please someone explain this to me

classic Classic list List threaded Threaded
53 messages Options
123
Reply | Threaded
Open this post in threaded view
|

Re: Please someone explain this to me

Michael Van Canneyt


On Thu, 11 Feb 2016, Anthony Walter wrote:

> Michael, a question:
>
> How much of the interface section of units differ per platform? Is it 1% of
> the code? Is it 5% of the code? With the xml2 unit it's 0%, yet all of the
> declarations are nested in several layers of include files:

Numbers are irrelevant. A particular system is adhered to.
It's clearly not your system, but then, one could point out that it's not your code either.

Obviously, I cannot speak for Lazarus' LCL units.

I can only speak for the RTL units.

The files are like this for maintainability:
- Platform dependent parts will always be in separate include files.
   Forget IFDEF. The few parts where it is used are ugly enough as it is.
- Some interface parts are shared between units: see the unix-specific units
   as explained by Marco. Sysutils shares e.g. a part with the Strings unit.
   the DOS unit shares a part with the System unit, if memory serves
   correctly.
- Smaller files reduce the risk of conflicts when committing changes.
   While it is common for 2 people to work on sysutils or system,
   it's already less common that they work on the same functionality.

As said before, these files are organized for the sake of their maintainers.
Not the users. What the maintainers deem best, will be used.

Allow me to express some surprise at the vehemence with which you attack
this perceived problem.

First, it's not like the identifiers are distributed randomly over arbitrary include files.
They are neatly grouped in logical units.

Second, if you want a nice overview of what is implemented in a unit:
the documentation is guaranteed to be complete at the time of release,
and contains an index per unit and even of all identifiers in the RTL.
The sysutils unit documentation contains some topics with 'groups' of functionality.
(suggestions always welcome)

In Delphi, that's what I also do if I need an overview; I open the help, and that's it.
Only in the very last instance - if I am interested in the actual particulars of an
implementation - then I open the source.

And honestly, I cannot even remember when I had to look up something in
sysutils or system. I expect experienced people to know these units better
than the back of their hand. For beginners I think documentation is better
suited.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Please someone explain this to me

Michael Van Canneyt
In reply to this post by Anthony Walter-3


On Thu, 11 Feb 2016, Anthony Walter wrote:

>> This won't be changed. Period.
>
> Sven, not to be argumentative,

Funny.
You _are_ argumentative, considering the answers you got and number of posts :-)

(no offense intended)

> but you do get that for a long time
> programmers have learned how to write code and use libraries by examining
> them?

That may be true for ordinary libraries.

But the RTL is equivalent to Libc.

I suggest you hold a poll for the number of people that learned C (or C++)
by studying libc or libstd (or whatever it is called in C++).

I expect you will be disappointed.

Secondly, I don't think the sysutils or system units are a particularly good
example. They are a historical image of the attempts (and possible mistakes) of
Borland, Inprise, CodeGear, Embarcadero and now Idera, dating back to Turbo Pascal.

Hardly good study material for learning.

> My goal is simply to make it easier for the people who would want to
> pick up and start using Lazarus.

A most noble goal, which I wholeheartedly support !

Therefor I humbly suggest you continue your much-appreciated efforts in writing
much more documentation examples and tutorials, improve the documentation engine,
help out in getting fppkg and its upcoming web front end deployed.

I think that will help a lot more than us reorganizing the RTL unit files.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Please someone explain this to me

Mattias Gaertner
In reply to this post by Michael Van Canneyt
> Michael Van Canneyt <[hidden email]> hat am 11. Februar 2016 um 04:27
> geschrieben:
>[...]
> Lazarus IDE shows a tooltip when you hover over an identifier with the mouse.
> I suspect it will take one on the team less than 10-minutes to add the unit
> name to the tooltip, in addition to the package and source file name.

Done.

Mattias
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Please someone explain this to me

Michael Van Canneyt


On Thu, 11 Feb 2016, Mattias Gaertner wrote:

>> Michael Van Canneyt <[hidden email]> hat am 11. Februar 2016 um 04:27
>> geschrieben:
>> [...]
>> Lazarus IDE shows a tooltip when you hover over an identifier with the mouse.
>> I suspect it will take one on the team less than 10-minutes to add the unit
>> name to the tooltip, in addition to the package and source file name.
>
> Done.

It's a coder... It's a hacker... it's SuperMattias !

Michael.

PS. For those not familiar with the reference:
https://en.wikipedia.org/wiki/It's_a_Bird...It's_a_Plane...It's_Superman
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Please someone explain this to me

Graeme Geldenhuys-6
On 2016-02-11 11:51, Michael Van Canneyt wrote:
> It's a coder... It's a hacker... it's SuperMattias !

:-D   LOL




G.

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Please someone explain this to me

Sven Barth-2
In reply to this post by Anthony Walter-3

Am 11.02.2016 11:41 schrieb "Anthony Walter" <[hidden email]>:
>
> > This won't be changed. Period.
>
> Sven, not to be argumentative, but you do get that for a long time programmers have learned how to write code and use libraries by examining them? My goal is simply to make it easier for the people who would want to pick up and start using Lazarus. Organizing things better for the general developer population, and I'm not just referring to only source code organization, is something I honestly hope this community considers important. I believe that point should be a consideration not just for beginners, but also for the mass of professionals.

If they are just learning the language then they shouldn't poke around in the core units anyway. That's what the documentation and help is for.
Back when I started learning TP I didn't have the internet and I didn't have the sources of the units. I only had the help and it was definitely enough, so no I'm not even remotely convinced by your argument.
Also you aren't someone who's working on that code. New users aren't either. I am. The other maintainers are. *We* need to work in these units, not you. And thus the code is structured in a way that it is suitable for *us* not you.

Regards,
Sven


_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Please someone explain this to me

wkitty42
In reply to this post by Michael Van Canneyt
On 02/11/2016 06:51 AM, Michael Van Canneyt wrote:

> On Thu, 11 Feb 2016, Mattias Gaertner wrote:
>>> Michael Van Canneyt <[hidden email]> hat am 11. Februar 2016 um 04:27
>>> geschrieben:
>>> [...]
>>> Lazarus IDE shows a tooltip when you hover over an identifier with the mouse.
>>> I suspect it will take one on the team less than 10-minutes to add the unit
>>> name to the tooltip, in addition to the package and source file name.
>>
>> Done.
>
> It's a coder... It's a hacker... it's SuperMattias !

LOL! :thumbsup:

--
  NOTE: No off-list assistance is given without prior approval.
        *Please keep mailing list traffic on the list* unless
        private contact is specifically requested and granted.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Please someone explain this to me

Mattias Gaertner
In reply to this post by Anthony Walter-3
On Wed, 10 Feb 2016 05:10:55 -0500
Anthony Walter <[hidden email]> wrote:

>[...]
> Additionally, and in a different scenario, when the identifier IS defined
> and several units are in the uses clause the goto declaration can jump to
> an include file without any information pertaining to which of the units is
> including the file. To the best of my knowledge there isn't a straight
> forward way to figure this out,

If Lazarus has found the declaration there are a few features that might
help:

Search / Goto include directive. This will take you one step up.

Code Explorer / Surrounding

Source / Unit Information

Mattias
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Please someone explain this to me

Jürgen Hestermann
In reply to this post by Sven Barth-2
Am 2016-02-11 um 14:21 schrieb Sven Barth:
 > If they are just learning the language then they shouldn't poke around in the core units anyway. That's what the documentation and help is for.
 > Back when I started learning TP I didn't have the internet and I didn't have the sources of the units. I only had the help and it was definitely enough, so no I'm not even remotely convinced by your argument.

Strange that suddenly the documentation should be used
while in the past everybody else is telling me (and others)
to look into the code to understand it.

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Please someone explain this to me

Michael Van Canneyt


On Sun, 14 Feb 2016, Jürgen Hestermann wrote:

> Am 2016-02-11 um 14:21 schrieb Sven Barth:
>> If they are just learning the language then they shouldn't poke around in
> the core units anyway. That's what the documentation and help is for.
>> Back when I started learning TP I didn't have the internet and I didn't
> have the sources of the units. I only had the help and it was definitely
> enough, so no I'm not even remotely convinced by your argument.
>
> Strange that suddenly the documentation should be used
> while in the past everybody else is telling me (and others)
> to look into the code to understand it.
Nothing strange about it.

There is a difference between learning the language, which implies knowing
what routines are available to you, and understanding how a particular
routine works in detail. The latter requires you to study the source code.
For the former, you don't need the details: the documentation is the better
alternative.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: *** GMX Spamverdacht *** Re: Please someone explain this to me

Jürgen Hestermann
Am 2016-02-14 um 12:28 schrieb Michael Van Canneyt:
 > There is a difference between learning the language, which implies knowing
 > what routines are available to you, and understanding how a particular routine works in detail. The latter requires you to study the source code.
 > For the former, you don't need the details: the documentation is the better
 > alternative.

Here we differ:
I expect that a documentation *fully* explains
a behaviour of a certain function (or something else),
not just some part of it.

It's not neccessary to know *how* things are coded but
the underlying idea and what the programmer can rely on.
The code can even differ from the documenation in case of bugs!
So what does it help to look into the code?

If a documenation satisfies the above requirement then
there is no need to look into the code *in any case*.

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Please someone explain this to me

Andreas Schneider-7
Am 2016-02-14 12:42, schrieb Jürgen Hestermann:
> Here we differ:
> I expect that a documentation *fully* explains
> a behaviour of a certain function (or something else),
> not just some part of it.

IMHO that would be insane. To a programmer (like you and me) the RTL and
the Compiler are just interfaces. Therefore the documentation describes
the contract. I need not and should not need to know the inner workings.
All I need to know is the required inputs to get a specific output.
The more of the internals you guarantee, the less you can change later
on which might even make platform portability impossible.

Look for example at Java. You rarely found details about the JVM. If you
do, they are from "hackers", in blogs or the like. Oracle doesn't
guarantee you how the interfaces (RTL) are implemented. There are
certain constraints every RTL implementation has to fulfill and they are
documented. The rest is open to the one implementing it. And in reality
there are indeed quite a lot differences. The HotSpot VM works different
from JRockit which again works much different from IBMs implementations.

So again - in my opinion - internals are best left out of documentation.
Therefore *fully* explaining the behavior would be wrong.

Best regards,
Andreas
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Please someone explain this to me

Jürgen Hestermann
Am 2016-02-15 um 18:21 schrieb Andreas Schneider:
 > Am 2016-02-14 12:42, schrieb Jürgen Hestermann:
 >> Here we differ:
 >> I expect that a documentation *fully* explains
 >> a behaviour of a certain function (or something else),
 >> not just some part of it.
 > IMHO that would be insane. To a programmer (like you and me) the RTL and the Compiler are just interfaces. Therefore the documentation describes the contract. I need not and should not need to know the inner workings. All I need to know is the required inputs to get a specific output.
 > The more of the internals you guarantee, the less you can change later on which might even make platform portability impossible.

Fully agree, exactly what I was trying to say.


 > So again - in my opinion - internals are best left out of documentation. Therefore *fully* explaining the behavior would be wrong.

I would differentiate between "details" and "internals". Of course, the exact coding ("internals") should not be part of the documentation.
But the "details" - which I would name the behaviour under all (even rare) circumstances - should be fully documented.
There should be no doubt what I can expect and what not.

But in this forum very often when someone complains about missing or incomplete documentation he gets the advice to look into the code which IMO is insane because

1.) the code may change over time
2.) it can have bugs (which I would rely on)
3.) it is often hard to understand if I don't know about the surrounding concepts and other things.

Also, the documentation is very important for the programmer as it lets him think about what he is coding (and only the programmer knows what he had in mind when he coded something). I often found that my code was imcomplete or otherwise misconcepted as I tried to explain it to someone else.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
123