Bakcward compatibility sins

Maintaining backward compatibility is more of most important values for every software library, tool or system used by other systems via it's API. However, as system evolves, maintaining compatibility gets harder and sometimes it's not possible to improve it in a desired way, because that would mean breaking compatibility. At those points a tough decision has to be made: maintain compatibility or break it.
The list bellow is not complete by any means, but it shows few examples where I doubt that being backward compatible was the right decision. I also add what I think was the right decision and what we can learn from mistakes made.

1. WinMain [dead parameter in rarely used function]

   In Windows API, the programs entry point is as follows:
   int CALLBACK WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow);
   Note the second argument: it is always NULL!
   The idea is, that this argument had a meaning in 16-bit Windows, but that was completely removed in 32-bit Windows. So, this parameter is in effect meaningless and is here just for backwards compatibility. While that seem to make sense at first, consider that Win16 and Win32 are not entirely compatible! Applications had to be migrated from one to another. And application has exactly one WinMain.
   As a consequence, what you see here is short term backward compatibility (Win16 died quite soon after Win32 appeared) at the cost of long term API pollution. All for something as trivial as application entry point (that can be solved via preprocessor macro).

2. WPARAM ["hungarian compatibility"]

   In Windows the signature for Window Procedure is like this:
   LRESULT WINAPI DefWindowProc(HWND hWnd, UINT Msg, WPARAM wParam, LPARAM lParam);
   and the parameter in question is wParam, it's datatype to be exact.
   The point here is that "W" stand for "WORD" in both datatype and parameter name. This was true in Win16 (WORD=2 bytes), but not anymore since Win32 (WORD datatype still is 2 bytes, but WPARAM now is 4 bytes).
   There are two issues apparent here:

   • Hungarian notation is a bad idea and one of the reasons is in front of you (if you haven't noticed - parameter name LIES to you)
   • Generic datatypes (like int) are redefined as something else to make it possible to change them later. This was done in this case too, except that the name encoded the original type before and LIES to us now.
3. Double.parseDouble(null) vs. Integer.parseInt(null) [bug-compatibility]

   In Java:
   Integer.parseInt(null) // throws NumberFormatException
Double.parseDouble(null) // throws NullPointerException
   This inconsistency originated from old versions of Java and is kept here for backward compatibility. This is documented behavior, so it's "a feature".
   What this actually is, is called bug-compatibility. The funniest part is that both these methods can throw NumberFormatException, so a fix is quite simple and hardly will break badly something. I mean, if you handle exception properly, it will just work, otherwise you probably have a quite buggy system, one more or less doesn't make a difference...
   Most importantly, these two are very old. Double.parseDouble() dates to Java 1.2, no such number on the other, but probably around the same. YOU REALLY REALLY COULD HAVE FIXED THIS BACK THEN! Instead, Sun maintained backward, sorry, bug-compatibility, just to see the bug getting harder to fix later.

4. Java generics vs. C# generics [focus on past, not on future]

   Both languages fell into idea of object collections just to find out, that they destroyed a lot of type safety for more verbose coding (lose-lose situation, that is). How did they add generics later, without breaking languages backward compatibility?
   Java went the hard way by turning existing non-generic into generic. They faced three issues:

   • both non-generic and generic collections should be available (so that old code still compiles)
   • convertibility between generic and old non-generic variants (mix old and new code)
   • behavior compatibility (non-generic accepts anything, generic is limited)
   It was easy and correct to default to Object for non-generic collections. Problems arised for generic collections that are more specific than Object. Solution was to make generic argument a syntactic sugar, only available at compile time, that is collection is still like it was before, just casting is auto-added by compiler. This was done, because old (existing) collections always accepted anything, so if an exception is introduced for non-compatible type, an existing code would be broken. Non-generic collection was made convertible to any generic collection (whatever the argument is). That in turn added two new issues:
   • what happens is non-generic is converted to a generic with incompatible argument?
   • how type-safety is controlled in new code, when under the hood is the old non-generic collection?
   Java creators went the easy way in both these cases: they accepted ClassCastException for first and completely forbid direct conversion of one generic collection to other (i.e. List<Integer> can't be directly casted to List<Number>).
   What went wrong here? Four issues:
   • a generic collection can be passed to old non-generic code which is free to insert anything, that will only explode in new code!
   • no generic type can still be casted to other one, even if arguments are compatible, you have to work that around via cast through non-generic collection
   • generic only exists at compile time, no runtime type checking exists
   • you can't forbid new stuff to be generic-only, it still can be used without generic arguments, where Object is assumed
   What they could do instead? Make collections aware of their generic argument and throw exception, when incompatible object is inserted. That would accomplish the following:
   • type safety of generic collection - it will simply never contain incompatible objects
   • casting of references would simply work, as the protection is there at runtime
   • passing generic collection to old code would reveal bugs (object of wrong type inserted) or show invalid assumptions about it ("oops, it's not String-only collection")
   Yes, this approach could break old code. But the alternative, that was chosen, made all new code suck. Looking forward, new code will slowly outnumber old and Java as a language will have inferior generics than it could!

   C# took different approach here. It simply added generics as something completely new, not compatible with old in any way. Not ideal, as interoperability between old and new code is troublesome. But looking forward, old code will die out. So IMO it's a better approach, that that of Java

5. C++ compatibility with C [not quitting in time]

   So, C++ is designed to be compatible with C, that is "a valid C program is a valid C++ program", as they say... Well, not really for several reasons:

   • the compatibility is lost with the first new keyword introduced (*caugh* class *caugh*) - what used to be a valid identifier, now is not
   • C++ has different linkage because of name mangling, which makes it incompatible with C. Worse, now the C libraries are forced to add extern "C" markers under __cplusplus define, to make themselves compatible with C++
   • enums and structs have tag names in C, but these are real type names in C++
   What could they do? Well, actually they did the right thing, just for far too long. If C++ the goal was to completely replace C, it failed to to that. And it's long past the time to become an independent language and throw some old C junk away (well, you can introduce some constructs to access C from C++, we have so many of them, that few more doesn't really matter).
   What breaking ties with C would achieve:
   • string literals can become real std::string objects with their functionality (like concatenation using "+")
   • arrays can be std::array by default (being assignable is the first win)
   • a lot of standard C library could be wrapped by C++ function that would accept C++ types (imagine printf() accepting std::string)
   • forget extern "C", you could just have something like #cinclude for C headers

Lessons that can be learned

• A compatibility break, that is almost guaranteed to have a very small impact, is worth to do (WinMain)
• If you redefine some type via typedef, make new type more generic, so you can change it (i.e. "an integer of size, which is at least X")
• Hungarian notation is a bad idea, full one is ten times so
• Bugs should be fixed! A fix that breaks some small importance thing will give you few rants from people, who are the ones to ignore (I can't imagine good developer complaining about fixed bug, even if it broke something in his buggy code).
• New code or file format will gradually outnumber old one by large margin, thus look forwards, not backwards
• If you fail to maintain full compatibility, use it as opportunity to break for better future
• The number of "breaks" doesn't matter, what matter is overall pain introduced by compatibility break. So, if you broke something important, making minor things compatible wont help much.
• Bonus: it's not possible to maintain backward compatibility forever, plan break in advance and don't give false promises.

Exception handling is mostly a failure

In short: exceptions are good for system and critical errors (like out of memory). The simple and more expected error is, exception is less useful and more trouble.

Error handling is hard. Not doing it properly comes back with mysterious failures, where no one can understand was went wrong. Doing it properly is pain in the ass, mostly because it takes a lot of time to do a boring lot of coding, when stuff already works! Really, most of us probably just code the happy path first, prove it and then go on handling all the possible not so happy cases. This is generally the right thing to do - what's the point of handling the errors when you're not yet sure the solution is right?

Sinking among ifs

That's the general idea for exception handling. A typical example given to students is like this:

if(open_file()) {
  if(read_file()) {
    if(process_data()) {
      show_result();
    }
    else {
      error("Failed to process data");
    }
  }
  else {
    error("Failed to read file");
  }
  close_file();
}
else {
  error("Failed to open file");
}

The lines in bold are "good code". Everything else is there for error handling. It seems very nice to write all "good" function call one after another and move error handling code somewhere else - welcome try-catch!

try {
  open_file();
  read_file();
  process_data();
  show_result();
  close_file();
} catch(Exception e) {
  // determine and error message here
}

Nice, we have separated the happy path from error handling code, now it's easy to understand what code does!
The real life situations are not so nice...

There are different types of errors

• Disasters: something that generally shouldn't happen, like hard disk crash. Some errors are so rare and so fatal, that it's pointless to try preparing for them.
• Fatal errors: stuff that renders applications unusable, i.e. losing network connection is fatal for web application.
• Expected mistakes: user haven't filled required fields? Specified file name contains invalid characters? such types of errors are predictable and applications should be ready for them.
• Glitches: a string "15 " (trailing space) in 99% of cases is an integer number 15, dammit.

The interesting thing here is that exactly the same error can belong to different group depending on exact situation. Failure while writing to file can mean that primary hard disk has just crashed and in few seconds entire computer will be unusable, or it can just mean that user has unplugged the USB stick. Who said that failure to open file is fatal? No config - assume hard-coded defaults.

Opening file is so difficult

... So, we are opening a configuration file, that is not required to exist...

File *file = fopen(filename, "r");

Nice, NULL means it does not exist, otherwise it's something we can read!
What's the problem, you can write it the opposite way:

FileStream file = null;
if(File.Exists(filename)) {
  file = new FileStream(filename);
}

Does the same thing. Does it? Congratulations, you've just introduced full-moon bug! Files sometimes disappear, you know, get deleted. That can happen at any point in time, for example right between the existence check and opening... Fatal error, crash, or ... well, that file was never required to be there in the first place? So now code becomes:

FileStream file = null;
try {
  file = new FileStream(filename);
}
catch (Exception e) {
  // ignore
}

Wonderful, what used to be one line, now is... progress.

How badly you can blow?

C once again. You call a function and you expect it to return. Is this guaranteed? No! Application might die inside, but we don't care. longjmp() can be called, but we don't care again - unless we made it ourselves.
Let's "upgrade" to C++. What can happen now? Yes, exception can be thrown, and there are types of them! Worse: new types of thrown exception can be added in the future!
It's considered a good practice to only catch exceptions you do care about and let other populate up the call stack. That's fine, but what about the new types of exception that might be added in the future? It looks like someone didn't design for future...

Exception safety

There is an amazing thing about exception safety I still can't explain. C++ is a language that with it's standard library throws something extremely rarely. A topic called "exception safety" is part of it's books. When we come to Java and co., where exceptions are thrown here, there and everywhere, this is somehow forgotten...

obj.foo(x, y);

You can only guess, how foo works with x and y, but there's one thing most seem to assume - all or nothing. If exception is thrown out of foo(), you want the state of obj unchanged! Simple concept, but not so easy to get it right. Throw more exceptions and enjoy more full-moon bugs.

Exception specifications

This is something that pissed me off when I started learning Java. C++ has them too, but they are optional and no one seems to use them (except for standard library). Some even discourage it.
Looking at C#, they have thrown away specifications entirely.
Looking back at Java... ArrayIndexOutOfBoundsException, PersistenceException and multiple others are "unchecked" exceptions so you don't need to write them all over the place. Are the two I mentioned so "unexcpected"?

Conclusions

• Exception handling works well with critical errors. Less serious the error is, less efficient exception handling is. For simple errors exceptions are more trouble.
• Exceptions are designed to separate useful code from error handling code. When exception handling mechanisms appear inside of a nested code blocks, it's a first sign of exception misuse.
• I also haven't mentioned, that exception are also expensive in terms of performance...

How I'd fix Java

If I could change anything in Java, here's what I'd do:

1. Introduce string primitive
It would be just as the String class, except it would never be null, it would be empty string instead. How much boiler plate code does the null-checks cause for String. Autoboxing would work too.
As for consistency, other primitimes could also allow called methods of their relevant class alternatives.
2. Make generics array-like
By introducing generics Java creators worked hard to ensure backward compatibility. And, IMHO, failed. Consider:
• Array of Integer objects can be casted to array of Number objects, but not so collections.
• If you insert something illegal to such downcasted array, you get appropriate exception.
That's not the case for collections. The intent was clear:
• Collections were not designed to throw exception due to incompatible type, as they were designed to always hold Object references. Changing that could break existing code.
• Any down/up-casting was not permitted on generic collections for the same reason.
However, I think this wasn't the right thing to do, because:
• If you're not sure, what your legacy code inserts into raw collection, pass in the one, that hold Object and you'll get no issues.
• If the legacy code is supposed to only insert certain type (say String), so pass in appropriate collection. In case the legacy code inserts something else, you get exception at exact place where the bug in legacy code lays, rather than get an ugly ClassCastException miles away in the new code.
Finally, why not combine autobixing with collections, so that primitives could be stored in them? Well, I mean collections still hold references to wrappers, just you get autoboxing when putting/getting and not-null-ness is ensured.
3. Allow public fields by JavaBeans specification
Probably 90% of classes conforming with JavaBeans specification have only trivial setters and getters. I see no real reason, why public fields are not allowed and all this boiler plate code must be written.
4. Enhanced for should be null-safe
Why it's not called for-each, like in other languages?
This type of for statement was introduced for readability, but having to check for null takes away half of that, because you have to wrap it in an if (you can avoid if by writing apropriate condition in traditional for).
IMO this enhanced for should treat null collection as empty.
5. Allow pass-by-reference or multi-value returns
It really is nasty to write a new class just to return several values from method. I'd love to have something like C++ references or Pythons multi-value return for that.
6. Replace java.io entirely
Just admit - java.io is hopelessly overengineered. The most clumsy and least usable I/O system of all languages I've ever used. With this number of classes you'd expect to have stuff for all possible cases, but in reality there never is a class, that does what you need. You have to combine at least two of them in all cases. And if you need to read a simple text file, out of all there trouble all you get is readLine() - parse it yourself. How to fix it? Just make a clone of C++ iostream - with a couple of rough edges removed and couple extra classes (like for pipes and sockets) it would be nearly perfect solution.
7. Package aliases or smallest unique distinction
One thinkg I don't like about Java packages is the all-or-nothing approach with their names. In case you have 2 classes with same name, you have to use both of them with full package qualification. With standard reverse-domain naming scheme this means ugly long names. What I'd like is aliases, similar to C++ namespace aliases, which could look like:
package alias = com.company.product.whatever.pkg;
With this line alias.ClassName is identical to com.company.product.whatever.pkg.ClassName.
Another solution could be to use the unique part of package name: move backwards from class name to any dot until you get uniques name. Perhaps whatever.pkg.ClassName is enough to identify class and you don't need to type the full ugly package name.