How can we make it easier to experiment with the compiler?

[Alexandru Ermicioi]

On Monday, 24 May 2021 at 10:34:35 UTC, Walter Bright wrote:
> On 5/24/2021 2:44 AM, Alexandru Ermicioi wrote:
>> They are not simple for new volunteers to dmd.
>
> You're right, they are not. They're optimized for the people 
> who spend thousands of hours working on it.
>
> This inevitably happens with every profession, every 
> discipline, and every project. A jargon specific to it grows up 
> around it, for the convenience of the people who work on it 
> every day. If the jargon is consistent and reasonably logical, 
> it can be a great aid to understanding once one gets familiar 
> with it.

Well, there is no dictionary for those abbreviations, and it is 
hard, to decipher them when looking into kilometer long code. 
That is my experience with dmd code:
1. I stumble on compiler bug.
2. File a bug report.
3. No-one fixes it in couple of days, and I think perhaps I can 
fix this bug, since it's not complicated, and should be couple of 
lines.
4. I download dmd, try to compile it somehow, because dub 
compilation either freezed, or failed, but somehow manage to by 
using older build system dmd had.
5. Then finally I can start changing code?
6. No, first find what module and class is responsible for that 
code, in ocean of modules named from an ocean of abbreviations, 
or with misguiding names.
7. Oh well after wasting an hour/two of from 3 to 4 what you 
have, you find it.
8. Then you look into the kilometer long function. You seem to 
find the piece of code that might be the cause of the bug, and 
try understanding it better.
9. You read that said code, try keeping in mind entire code flow 
you've read up to this point, and suddenly there is an 'aa'.
10. You try to figure out what 'aa' means, but fail to do so, 
therefore you need to look ad it's declaration to know the type 
and figure it out from it's type.
11. You find the type of variable, and rejoice at deciphering it 
being 'associative array', yay.
12. Okay, let's go back to the line with 'aa'.
13. First find that said line if for some reason your ide didn't 
retain it.
14. Once there, you continue reading, but wait,what was before 
the line with 'aa'?
15. Damn, I forgot. Sigh I have to read all the code again.


That is my experience with all abbreviations in dmd, which are 
like an ocean.
It is ok, to have a couple of well defined and documented 
abbreviations, not an ocean of them without any documentation. It 
is not my job, to fix dmd, I wanted to do something when I had 
couple of hours to invest. It is not rewarding when those couple 
of hours are wasted at deciphering abbreviations, and not even 
understanding the flow of code itself.

Please limit use of abbreviations to minimum, and those that are 
used, should be documented.

>
> There are some reasonably well-encapsulated parts. The lexer, 
> the parser, and the files in the root package. To understand 
> the compiler, I'd start there.

Yet there is no official guidance on where to start. Also, please 
note that not all volunteers prefer reading source code, and 
invest hours at understanding the architecture and inner 
workings, starting from lexer or parser, some of them just want 
to fix a small bug, and be done with it. It is extremely hard to 
do that now.

Best regards,
Alexandru.