Opinion of February 2012

[H. S. Teoh]

On Fri, Feb 03, 2012 at 05:12:08PM -0600, Zachary Lund wrote:
> Here are some things I'm unhappy with currently.
> 
> 1. Documentation
> 
> I find certain things, of which I will start writing down and
> writing patches for, in the documentation that are unsatisfactory.
> Two in particular is the current situation with memory management
> and CTFE. "delete" is planned for deprecation and alternative
> methods for custom de/allocators are already in place, yet most
> people don't even know about them or how to use them. I see talk on
> IRC about things that completely confuse me as to the state of
> things and I can generally find no obvious or reliable source of
> information. It's completely frustrating.
> 
> Documentation is much more important than feature implementation.

I agree with this. Based on current documentation, I didn't even know
the GC can be replaced at compile-time until someone mentioned it. And
up to now I still don't know how exactly to do this, since I couldn't
find any docs for it.

Some of the docs on the website are also deficient, for example std.uni
(which I already filed a bug for), due to missing doc comments in the
code.

I'd like to help. My D coding skills are still not up to snuff for
fixing the hard stuff, since I only just started learning D. But doc
comments I can do. However, there's no documentation that I can find
that describes the procedure for sending contributions. Such as where to
upload patches, what format they should be in, how to get diffs in the
right format, etc.. All this should be documented so that willing
contributors can jump in immediately, instead of being put off by having
to jump through unnecessary hoops (like hunting for possibly
non-existent documentation on how to contribute).

Another big missing with the documentation is a timestamp. The problem
is that some of the docs are out-of-date, but it looks identical to the
up-to-date pages, so it's very confusing for someone who doesn't already
know the answer. If you try something the docs say but it doesn't work,
then instead of pulling your hair out, you can look at the timestamp
that says "last updated 2005" and know that perhaps the info is out of
date and it isn't some bug in your code.

Timestamps will also tell potential contributors which pages to work on,
if they notice the info is wrong and/outdated.

Of course, this doesn't replace keeping the docs up-to-date, but it's
better than nothing.


[...]
> 3. FAQ
> 
> I think there was a discussion somewhere (of which I can't find now
> through Thunderbird search) but the FAQ is important. When people
> wonder about a feature of D, the first thing they should do is check
> the FAQ to find the answer.
> 
> I think that each time a solution is provided that might or might
> not be obvious, the reasoning behind that solution should be posted
> on the FAQ. Nothing should be left with abstract reasoning (outside
> of perhaps philisophy-based reasoning).
> 
> The FAQ is incomplete.

Agreed. I'm thinking the FAQ should include common newbie mistakes /
surprises, so that newcomers won't get overly frustrated with bugs that
are actually very simple but they have no idea how to fix it.


> 4. Microsoft
> 
> Windows. I cannot stand Windows. If Microsoft suddenly went bankrupt,
> Windows was never updated, and people had to move to MacOS or Linux, I
> would be the happiest man alive.

Ahhhahahaha... I wish this were true too. ;-)


> Unfortunately, this will seemingly never be the case and it stands
> that Microsoft has the highest share of all the OS users. Thus, it
> should be given higher priority to attract more users. When people
> complain about D not having large Windows support (or COFF support in
> particular and the shitty optlink), it kills me a little on the
> inside.

I agree, though I can't do very much to help on this front 'cos I
haven't done any serious work on windows for the last 10 years. (I
almost fell out of my chair (for joy) at my interview for my current job
when I found out that they used the gcc toolchain for development --
there was no indication of this on the job posting.)


> This is probably a lost cause but I've recently seen various
> complaints about the name "D". It's not distinct nor is D old enough
> to be known like C or C++ is. I remember a comment about the name
> "Mars" which I think would have been much more distinct and clearcut,
> and would have caused less issues.

I tend to agree too. The name "D" never fails to raise an eyebrow with
my friends when I mention that I'm learning it -- they regard it as the
next joke in the sequence C, C+, C++. (I know there is no such thing as
C+, but that's what your average layperson thinks.) It's also very hard
to search for online, since there are too many irrelevant matches.

But yeah, it's a lost cause. Especially now that Andrei's book bears
that name in print. It will be almost impossible to reverse the effects
of that.


[...]
> The .c extensions on C++ files... need I say more? That itself is a
> joke and seems to have been ignored when complaints about it came up.
> I've just recently been told that DMD was mostly implemented in C
> which is false. This situation is needlessly frustrating.

Now *that* is evil.


[...]
> I like the D language. Not so much the projects that surround D.

I like D too. I'd like to help in whatever way I can to make it a
successful language. I hope I will never have to go back to that
creeping horror known as C++.


T

-- 
Guns don't kill people. Bullets do.