Developer Tip: Defining an API

Ok, enough blather about theory, company politics, and other crap. How about something useful to an everyday developer?

When defining an API, make it as simple and as obvious as possible what data is actually being passed across the API.

1. This will make the API much easier to document - the names of the fields in the structures/objects/messages will be mnemonic, and you can document them as comments in the IDL file.
2. You can use an IDL translator to convert from one IDL to another, like RPC to CORBA, or from one language to another, like C to Python
3. You can automate the argument marshalling code if you want to write one or both sides of the API in another language.

An example I have seen that violates this was an API that wrapped all the arguments inside functor objects that were templates typed by the number of arguments they took. It's a great utility mechanism, because all your calls across the API are compact, taking one argument, and no return value because the functor inside will handle all that when the callback is made.

HOWEVER, this API was aboslutely miserable to develop with, because you had to go deep into the code on both client and server sides to discover what the arguments being passed really were. We wanted to build a test framework to exercise a server, but we had to manually build the structures populate the arguments, instead of being able to build them automatically from the IDL files.

A counterexample is a typical RPC interface to C programs. It will have a number of structures defined in the .x file, and it's a small matter of programming to build, buy, or Google a program to parse the .x file and produce the other files to build a test scaffold from in the language of your choice.

---

Technorati Tags --
Software, SoftwareDevelopment, Computers, Programming

A bit of explanation

Why is this blog called "Ninja Software Development", you may ask?
(Well, you might ask. Someone might. Ok, nobody would, but I'm going to explain it anyway)

It's not from a fannish infatuation with the Ninja as super-stealthy assassins, or an anime fixation. The key elements that I wished to convey were the secrecy of the ninja, and their resistance to a stronger force. The forces of business are arrayed against the development of good software, and the developers need to work behind the scenes to counter the greater army.

A colleague of mine once commented that it was a sad state of affairs when developers had to resort to skunkworks methods to improve software quality. He was right, in that the business risk management practices often require the reduction of change, which mean that quality changes will be delayed, and the business case of quality improvements is hard to make. And that, given the current business climate of making the numbers for the current quarter, means that nobody wants to spend time developing things with no new features. So the only way to improve software quality is to do so stealthily, since process improvements are equally difficult to make a business case for these days. Refactoring is done as part of a new feature; algorithmic changes are slipped in as a bug fix. And thus are we able to keep entropy at bay.

---

Technorati Tags --
Software, SoftwareDevelopment, Computers, Programming

Lots of programmers == lots of trouble!

Yesterday I backranted about offshoring, particularly to India. I discussed a number of things that I feel are difficulties for corporations offshoring to India. I forgot a more fundamental difficult for the company wanting to hire India programmers.

If they are intending to hire directly, they will be running into a problem of scale.

For a typical American job opening, a company may get (for example) 100 applications. About 50 will be dropped immediately for various reasons. Around 30 will be dropped at first resume review for insufficient capabilities. From the remaining 20, 10 will be picked as the best qualified, and get phone interviews. The field will be narrowed to 4, and the interviews will pick the best 2 of them to make offers to. When all is done, the company can feel reasonably certain that they have made a good choice in hiring the best qualified candidate.

Now consider this in India - where the number of incoming resumes is an order of magnitude larger. Instead of 100 applications, there are 1000. Assuming a typical bell curve (India may have a lot of good programmers, but statistics says that they will have an equivalent number of bad ones!), 500 of these will be dropped immediately, for the same sort of reasons as the previous example. Another 300 will fail to pass a resume review. This leaves 200, which will be sorted to 100 "best fit" candidates. Now, phone interviews for 100 people will be much less effective at narrowing down the field, compared to interviews for 10 people (assuming that phone interviews are even done in India, in which case this point is even more valid), so it will be a much more random selection out of the final 100 to get the 10 to interview. This boils down to a less-good fit for the selected candidate. And this does not even consider the amount of time to interview the larger number of "final" candidates!

Now, some would suggest that this can be countered by using local firms to do the hiring. I don't think that this will improve the situation much, because if the people hiring are not those who know what the position requires, they will not find people who match the need.

---

Technorati Tags --
Software, SoftwareDevelopment, Computers, Programming