Safe API Upgrade

First consideration for any Application Programming Interface (API) is how it will evolve in the future.  This critical interface must stand the test of time, and should whenever possible be both upgrade and downgrade compatible. 

What is wrong with this code?

It is code review time, and I offer a sample of Java code for you to critique.   Can you find the problems?

Eliminate Useless Comments

Be careful what you ask for.   I was reviewing some code that had absolutely no comments. I asked the developer to add some comment.   So, indeed they did, however the comments added no value to the code at all.   There is no point in adding comments for comments’ sake.  In fact, useless comments make the code worse by adding lines without adding value.   Let’s talk about what a valuable comment is.

Advertisement

Let Me Save Incomplete Files

This is a usability problem that I have run into a number of times.   A programmer writes a UI screen to receive a long list of inputs in order to create an object in system.  Save is enabled only when all the inputs are filled in and verified valid.  This is a big problem.

The Magic of MemFile

In the Purple Utilities Library is a class called MemFile which you can efficiently stream into and out of. Learn to use it properly can increase the efficiency of your programs when reading and writing data.

Don’t Interview the Engineer

This post is advice for managers looking to hire good engineers.  If you put a lot of value in the quality of the job interview, you might be selecting for the wrong kind of candidates.

Return Null or Exception?

I am writing a getter function, and the requested object can not be found.  Do I return null?   Or do I throw an exception?  The answer is “it depends.”  Sometimes both options are needed, but how to decide?

Variable Names & Key Values

Constructing JSON in Java can be a bother.  The most standard JSON library requires objects to be created, and then called to put the members on there.  So much easier in JavaScript, but it is not Java script.  Still, one technique to improve the readability is to name the variable in java to match the key in JSON.   Simple concept, easy to do, I sometimes wonder why it is not obvious to all.

Write Bug Reports to Last

Encountered a bug report that cited a problem in “the new build.”   That is not good enough, because every week will bring a new “new build.”

Keep Things the “Same”

This general design principle does not mean to never change anything, but to consciously create a paradigm where the same things have the same names and are accessed in the same way as much as possible.