One of Changeset Consulting's clients is working on modernizing a legacy web application; we're improving both its structural underpinnings and its user interface and outgoing APIs. It is like we are Chief O'Brien in the first season of Star Trek: Deep Space Nine, surveying and retrofitting Terok Nor. But that's not a fair comparison; O'Brien has to not only grapple with alien engineering approaches, but with the resentful and deliberate trashing the Cardassians inflicted on the station before handing it over. I haven't seen Stargate Atlantis but perhaps that's a better analogy; with every component of this long-asleep lost city that we resuscitate, a new console or room shimmers to life. Which is pretty rewarding!

The original authors wrote this application in Java. I've never worked on a Java application before, so the last few weeks have been quite an education in the Java ecosystem, in its tools and frameworks and libraries. We're improving the installation and deployment process, so now I'm more familiar with Ant, Gradle, Maven, OpenJDK, JDBC, Hibernate, and WildFly. I've gotten some API documentation in place, so now I know more about Spring and Javadoc.

As I was explaining to a friend this weekend, the overwhelming thing isn't Java as a language. It is a programming language and you can program in it, fine. The overwhelmption is the seemingly endless chain of plugins, platforms, and frameworks, and the mental work to understand what competes with, supersedes, integrates with, or depends on what.

Imagine you come to visit New York City for the first time, and wish to visit a specific address. First you need to work out where it is. But you do not have a map; there is no unified map of the whole place. Surely you can figure this out. Watch out: if someone doesn't tell you what borough an address is in, it's probably in Manhattan, but then again maybe not. There are multiple streets with the same name, and "31st Street and Broadway" in Queens is quite far from "31st Street and Broadway" in Manhattan. The avenue numbers go up westwards in Manhattan, eastwards in Brooklyn, and northwards in Queens. And so on.

You ask around, you see sketches of maps other people have made on their journeys, and eventually you feel pretty confident that you know the rough distance and direction to your destination. Now, how do you get there from your hotel room?

You probably don't want to walk all the way; for one thing, it's illegal and dangerous to walk on the freeways. This is why we have the subway (express and local), and buses (express and local, both privately and publicly run), and government-regulated taxis (street-hailable cabs and private car services), and bike rental, and commuter rail, a funicular/tram, car rental, ferries, and so on. Also there are illegal rideshare/taxi services that lots of people use. You try to learn some nouns and figure out what sort of thing each is, and what's a subset of what.

A MetroCard works on some of these modes and not others, and some transfers from one ride to another cost you nothing, and you can't use an unlimited-ride card twice at the same station or on the same bus within 18 minutes.* You can bring a bike on some MTA-run services but not all, not all the time. There are whole neighborhoods with no subway service, and whole neighborhoods with approximately no street parking. At rush hour the trains get super full. Service changes at night, on the weekend, and on holidays. Cars and buses get stuck behind accidents and parades. People and signs in Manhattan refer to "uptown" and "downtown" as though they are cardinal directions; they often correlate to "north" and "south" but not always. Metro North trains terminate at Grand Central, but Long Island Railroad trains terminate at New York Penn Station, which is named after Pennsylvania because it's where you can catch a train to Pennsylvania,** and there's a Newark Penn Station too but over a crackling loudspeaker those two station names sound very similar so watch out. And so on.

You're lucky; you find a set of cryptic directions, from your hotel to the destination address, based on a five-year-old transit schedule. It suggests you take a bus that does not exist anymore. Sometimes you see descriptions of travel that you think could be feasible as a leg of your journey, and you read what other people have done. They talk about "Penn Station" and "the train" without disambiguating, refer to the subway as "the MTA" even though the MTA also runs other transit, talk about "the 7" without distinguishing local from express, and use "blocks" as a measure of distance even though some blocks are ten times as long as others.

Aaaaagh. And yet: you will make it. You will figure it out. New Yorkers will help you along the way.

The decades-old Java ecosystem feels overwhelming but this application overhaul is like any other task. Things are made of stuff. Human programmers made this thing and human programmers can understand and manipulate it. I'm a human programmer. I made Javadoc do what I wanted it to do, and now the product is better and our users will have more information. And every triumph earns me a skill I can deploy for other customers and groups I care about.

* Just long enough for you to enjoy a little break from the podcast you're making with President Nixon!
** Also see St. Petersburg's Finland Station.