On Wednesday, 8 June 2022 at 08:26:02 UTC, bauss wrote:
> On Tuesday, 7 June 2022 at 21:28:30 UTC, Paul wrote:
> I am not an expert programmer (although I work in software every day). I'm more of a system designer. Dlang has really made a big difference in our little company and we are truly grateful to have it. However, one thing I miss from my PHP days (I know - script languages - Ugh), is having public comments below each manual page.
Having the public post examples, gotchas, and other helpful information made a world of difference in learning the PHP language, all the while having the "source of truth" directly above.
Just suggesting that it might help increase adoption rates (PHP is very popular). Managing comments does take time, but then so does managing this forum.
Anyway, no ideas are bad ideas, so I felt I should post. I hope it is helpful.
Personally, I don't like it. I don't think good documentation needs comments to explain the content.
The reason why it's good for PHP is mostly because of how unintuitive and inconsistent it really is sometimes.
As you said yourself, it's good for gotchas etc.
D doesn't really have any gotchas in that sense since it's much more strict, not just in the sense of its language, but also how the standard library is written.
Most gotchas in PHP stem from inconsistent function names, arguments and the fact it's dynamic typing.
D has very consistent naming of functions, order of arguments and it's static typed.
Most other language documentations don't have a comment section either and probably because they're documented well too.
While PHP has improved and keeps improving, then it still let's most of is garbage linger around.
I see your point Bauss. I suppose I am not yet experienced enough with D.
Here is an example. Working with one of our programmers, he could not understand the following (sorry for my newbie simplistic example and understanding of D):
if ( a_name.exists ) ...
Where a_name is a string argument passed into the function. He felt that it was checking if the string has a value and could not understand why. It was a surprise to find that "exists" is actually a uniquely named D function that actually means "fileexists". Same with copy and remove.
Later, a more senior developer suggested we alias these names to be more readable, and easier to search for (we have a mix of D code, JS, and even our own class methods with similar names).
Maybe public comments like this within the manual could help with understanding and help improve the accessibility and adoption of D?
Regardless, D is wonderful, and we are thankful to have it. We hope D achieves widespread adoption it so that our company can rest assured that the project will live on. Sadly, a big deciding factor is risk mitigation (particularly by venture capitalists) and access to experience developers, who are all looking at this in the same way. It is very frustrating to hear "Why would we want to code in D? Who uses D?" when we know with 100% certainty that D significantly reduces our development time, and increases the reliability and maintainability of our software. And likewise, when a programmer says "I cannot understand the manual. It seems to be written for D experts only" it feels like a punch to the gut.
D is brilliant once you get into it. We will do whatever we can to help it spread.
Thank you for listening.