Phobos - breaking existing code

[Steven Schveighoffer via Digitalmars-d]

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