On 11/30/14 6:03 PM, Walter Bright wrote:
On 11/30/2014 7:28 AM, H. S. Teoh via Digitalmars-d wrote:
I think the complaint was not so much the fact that the code broke, but
the fact that it broke *without any clue as to how to fix it*.
Yup. Consider the fnmatch => globMatch change. Just edit the name,
right? Easy-peesy, right? But:
1. the guy given the job of updating the software is not the guy who
wrote it - he doesn't know what the code is intending to do
2. He gets "fnmatch is undefined"
3. there's no documentation for fnmatch anymore. He has no idea what
fnmatch is supposed to do. Now he's got to embark on some sort of
forensic search through old versions of the compiler, and not having
much clue which ones to look at
4. he figures out what it does, then starts poking through the Phobos
documentation looking for something that might work
5. he finds globMatch, it looks like it'll work
6. hopefully he's got a good test suite to verify that it is actually
the correct replacement
A simple name change has turned into a fair amount of work.
Now, if we had something like @disable with an optional message, we
could do
something like:
@disabled("Please use globMatch instead") auto fnmatch(...);
At least in theory, this would fix the problem. Of course, in practice,
things rarely work out so nicely except in retrospect. :-P
Keeping around a deprecated alias translating the old symbol to the new
one is a good approach. For a more detailed message, instead of the
@disabled enhancement, a simpler way is:
void fnmatch()(...) {
static assert(0, "use globMatch instead of fnmatch");
}
I propose a new feature:
/++
globMatch does blah blah blah
Oldname: fnmatch
+/
dmd -checkoldnames myoldproject.d
Error: fnmatch not defined. Note: globMatch says that it used to be
called fnmatch.
It isn't often we change names of things just to change the name. And if
we do, it's because the name is so bad. I agree with bearophile, the
name of things is *very* important, and shouldn't be prevented from
changing.
Note, we could add ddoc comments for moving symbols to different modules
too.
/++
Movedname: sleep => core.sys.posix.unistd.sleep
+/
I can't help but think that some sort of version(CompiledWith2065)
statements wouldn't help, but they would be really messy. I like the
idea of including old names in the docs, because that's really where it
should be, and it adds a note in the documentation. It can also be
amended retroactively when people find those cases, and it's
documentation. Documentation changes don't require any unit tests or
special explanations, they are just documents.
Making it usable by automated tools can only help.
-Steve
