On Tuesday, 25 May 2021 at 04:21:08 UTC, Ola Fosheim Grostad wrote:
> Nobody that has read an introductory book on compilers need a comment explaining a function that is looking up a symbol from a symboltable. If that is a problem, improve the name, use a longer name.

Of course, it is nice to know that that lookup(symbol) can return null, but that should be visible in the signature.

That can be covered by some "nullable/notnullable" or "optional" wrapper. Just follow some established coding guidelines for signatures.

I guess my point is: there is a big difference between documentation for a public API where the user is not supposed to read the code and internal relations in an application.

On Tuesday, 25 May 2021 at 04:21:08 UTC, Ola Fosheim Grostad wrote:

> This is not helpful. Too much commenting makes the code even harder to read and drowns out important comments.  This corporate illness (which assumes that programmers are idiots) is why editors now ship with hide-all-comments functionality... Good code with good naming needs only few comments and those are on an _algorithmic_ level.

You can't encode the full semantic into one function name with parameter names without to over blow these names.
Though, I concur with you for better naming, at least no abbreviations.
I even find the code to be more structured with comment blocks, in my eyes it aids to visualize the code structure better.


> Nobody that has read an introductory book on compilers need a comment explaining a function that is looking up a symbol from a symboltable. If that is a problem, improve the name, use a longer name.

+1 for `Symbol lookUpSymbol(string symbolName)`

However, small comments inside the function would also be beneficial.
A good example of comments is the ast module of nim:

https://github.com/nim-lang/Nim/blob/devel/compiler/ast.nim

On Tuesday, 25 May 2021 at 08:32:46 UTC, sighoya wrote:
> You can't encode the full semantic into one function name with parameter names without to over blow these names.

We can assume that the reader has read a book on compiler design and is familiar with the terminology and the most common algorithms. Provide a reference to wikipedia if unsure if the reader is with you...

Functions that are only called from a few places can have long descriptive names, that is not a negative.

> However, small comments inside the function would also be beneficial.

Yes, obviously. But adding 6 lines of comments for every trivial function is not helpful. It is a useless policy. It is a policy for the sake of having a policy.

If time is invested in documenting things that should be changed... then change becomes less likely: "look, the documentation is over there, change not needed".

Anyway, documentation is the wrong solution to structural issues. It does not enable anything.

It is kinda like saying a city does not read roadsigns because there is a good map available. Or that a city that is a labyrinth of one-way streets are easy to navigate with the right kind of map. Driving while looking at a map is not a good experience. And when things change, can you then trust the map?

*shrug*

On Monday, 24 May 2021 at 20:45:11 UTC, Andrei Alexandrescu wrote:
> On 5/24/21 8:38 AM, zjh wrote:
>> Small refactoring is useless.
>> `Big changes` are necessary.
>
> That evokes the couple who had problems in their relationship, so they decided to solve them by getting married.

You watched "Better Call Saul", didn't you? :-)

On Monday, 24 May 2021 at 02:56:14 UTC, Walter Bright wrote:
>
> The #1 problem isn't directories, it's "every module imports every other module" that leaves one with nowhere to start.
>

> I regularly fend off attempts to have dmd/root import files from dmd, and dmd/backend import files from dmd. I recently had to talk someone out of having dmd/backend import files from dmd/root.
>

Wow - that's pretty fundamental. How does such code get in? I assume you own the DMD code - all changes should be vetted and approved by you?

Btw one less from Linux maintenance is that the the owners should spend all their time reviewing code - not writing code!

On Tuesday, 25 May 2021 at 09:05:26 UTC, Ola Fosheim Grøstad wrote:
> On Tuesday, 25 May 2021 at 08:32:46 UTC, sighoya wrote:
>> [...]
>
> We can assume that the reader has read a book on compiler design and is familiar with the terminology and the most common algorithms. Provide a reference to wikipedia if unsure if the reader is with you...
>
> Functions that are only called from a few places can have long descriptive names, that is not a negative.
>
>> [...]
>
> Yes, obviously. But adding 6 lines of comments for every trivial function is not helpful. It is a useless policy. It is a policy for the sake of having a policy.
>
> If time is invested in documenting things that should be changed... then change becomes less likely: "look, the documentation is over there, change not needed".
>
> Anyway, documentation is the wrong solution to structural issues. It does not enable anything.
>
> It is kinda like saying a city does not read roadsigns because there is a good map available. Or that a city that is a labyrinth of one-way streets are easy to navigate with the right kind of map. Driving while looking at a map is not a good experience. And when things change, can you then trust the map?
>
> *shrug*

I don't know...I mean it's a start...

I feel like this forum has ADHD sometimes. A week ago it was all up in arms about ImportC, now it's fcused on this, two weeks from now this will be forgotten and on to something else...

On Tuesday, 25 May 2021 at 11:22:24 UTC, jmh530 wrote:
> I don't know...I mean it's a start...

Many functions have two-liners documentation already, but it is kinda like a forest. You see lots of individual trees, but the shape of the forest is hard to grasp. More documentation on individual functions won't enable anything. Just like stapling "this is spruce", "this is birch" to individual trees does not help much.

> I feel like this forum has ADHD sometimes. A week ago it was all up in arms about ImportC, now it's fcused on this, two weeks from now this will be forgotten and on to something else...

You have to build consensus somehow.

Most of the new cool features other languages get is bette done using a dedicated high level IR. There is currently no easy way to experiment with that for D (short of writing your own backend).

I think that is a road block.

On Tuesday, 25 May 2021 at 11:40:42 UTC, Ola Fosheim Grøstad wrote:
> On Tuesday, 25 May 2021 at 11:22:24 UTC, jmh530 wrote:
>> I don't know...I mean it's a start...
>
> Many functions have two-liners documentation already, but it is kinda like a forest. You see lots of individual trees, but the shape of the forest is hard to grasp. More documentation on individual functions won't enable anything. Just like stapling "this is spruce", "this is birch" to individual trees does not help much.

Or let me explain it another way. Assume writing good useful documentation takes 10-20% of your coding time.

What should you formally document?

1. High level structure.
2. Stuff that is stable and well encapsulated and needs to be explained.
3. FAQs.
4. Functions that deviate from the norm (behaves in surprising ways).

Stuff you want to replace, not so much I think. Given that those 10-20% would be better spent refactoring.

On Tuesday, 25 May 2021 at 12:21:23 UTC, Ola Fosheim Grøstad wrote:
> [snip]
>
> Stuff you want to replace, not so much I think. Given that those 10-20% would be better spent refactoring.

Ultimately Walter needs to think about how he best spends his time.

Refactoring won't happen overnight and more people who understand the compiler the more can assist with that and other things in the meantime.