Re: Deprecate vs. discourage

[Neil Jerram]

address@hidden (Ludovic Courtès) writes:

> Hi Neil,
>
> Neil Jerram <address@hidden> writes:
>
>> address@hidden (Ludovic Courtès) writes:
>>
>>> That’s what had been done for these functions but libguile also supports
>>> ‘discouraged’ features.
>>
>> I never really saw the case for two levels of deprecation
>> (i.e. `discouraged' and `deprecated').  I thought `deprecated' on its
>> own was enough.
>
> I think I get your point.  OTOH, I felt that /deprecating/
> ‘uniform-vector-{read-write}’ might be a bit strong, as it will annoy
> people who’ve been using them even though these functions are harmless.
>
> What do you think?

If we had a perfect manual, the recommended way to do something would be
documented there, and people writing new code would use that and so
naturally use what we currently believe to be the best thing.

If something like uniform-vector-xxx stops being the recommended
approach, but remains trivial for us to support in the codebase, I think
it is enough `discouragement' just to remove it from the manual.  That
will make it less likely to be used in new code.

I think we should use the formal deprecation mechanism for something
when it becomes a burden (of any kind) for us to continue support that
thing in the codebase, or when we have a good reason to believe that it
will become a burden soon.

Does that make sense?

> Thanks,
> Ludo’.

     Neil