29

I've recently come across a Python library on GitHub. The library is great, but contains one glaring typo in a function name. Let's call it dummy_fuction() while it should be dummy_function(). This function is definitely "in the wild" and most likely used in embedded systems.

The first thing that springs to mind is to add a second version of the function with the correct name and add a deprecation warning to the first version for the next release.

Three questions:

  1. Could the approach above have any unintended consequences?
  2. Is there a standard approach to this kind of problem?
  3. How long should any deprecation warning be left in place?
Jamie Bull
  • 464
  • 3
  • 11
  • 1
    This is a situation (even though not a very frequent one) in which a static language is much more robust than a dynamic one: a compiler could check if your renamed function already exists. – Giorgio May 02 '14 at 10:08
  • 7
    see also [HTTP referer](http://en.wikipedia.org/wiki/HTTP_referer) [sic] – AakashM May 02 '14 at 13:35
  • 2
    I would also point out Apache's [mod_speling](http://httpd.apache.org/docs/2.2/mod/mod_speling.html), but that might have been intentional. – Reinstate Monica -- notmaynard May 02 '14 at 15:47
  • 1
    @AakashM: I love it how the Wikipedia article now uses both the incorrect and correct spelling throughout that page (even when referring to the object, not the term), with the misspelled version being more prevalent! – Martijn Pieters May 06 '14 at 10:30
  • Another good bit about the `http_referer` - "Its like when I did the referer field. I got nothing but grief for my choice of spelling. I am now attempting to get the spelling corrected in the OED since my spelling is used several billion times a minute more than theirs." - [Phillip Hallam-Baker](https://groups.google.com/forum/#!original/alt.folklore.computers/7X75In21_54/JgV9Rw04f-EJ) – Jamie Bull May 07 '14 at 09:16

1 Answers1

29

First and foremost, the policy depends on the maintainer.

I think your question is interesting, but mostly opinion-based.

In my personal opinion your approach is sound - rename the function and leave the misspelled version as a deprecated artifact, redirecting to the correct one.

Could the approach above have any unintended consequences?

It could break the code eg. if someone couldn't stand the misspelling either and implemented a renamed version of their own. Now there'll be a name clash once they update the library.

Is there a standard approach to this kind of problem?

Don't make spelling mistakes when writing a library ;)

How long should any deprecation warning be left in place?

I believe the deprecation should be left in place until the next major release (when the first digit in version number is increased).

This is when some - justified - backward compatibility breaking is tolerable, and it's up to the library users to ensure their code still builds fine.

Just make sure to point it out in the changelog: guys, if you used dummy_fuction, replace it with dummy_function everywhere and you're good to go.

If the library isn't versioned, as it might be - it makes a good case to start versioning it.

Konrad Morawski
  • 9,721
  • 4
  • 37
  • 58
  • 1
    Good to hear. The library is versioned so the approach to version control sounds good. It actually has its own IDE so the misspelled version can be hidden from the code-completion tool which should stop new users using it. If I could give you another +1 for the answer to Q2 I would! – Jamie Bull May 02 '14 at 10:12
  • 2
    This is the approach that I've seen in other software as well. I use a 3rd party API for a piece of software I develop, and their API contains a getter method that contains a typo. The issue was fixed by renaming the method, and creating a dummy method with the old (incorrect) spelling that simply calls the correct version. The dummy method contains no documentation other than to mention it's deprecated and a link to the correct version. That method has been there for *years* now, to avoid breaking any backwards compatibility. – Karl Nicoll May 06 '14 at 10:20