Hacker News Reader

Comment by crazygringo | Hacker News Reader

> they're a permanent reminder of how many times you got the API wrong.

I mean, that's clever for a tweet, but I hope nobody takes that seriously.

It's pretty counterproductive to view design through the lens of getting something wrong or right. There's just iteration in the direction of improvement. It didn't start out wrong -- it was your best first attempt with what you knew at the time. Then you learned more and so it improved. But it'll never be "right", just incrementally "more useful".

API's aren't mathematical proofs.

Just in case anyone needs to hear it ;)

View on HN

Seeing a project on a pretty high major is a positive signal to me. It tells me that they understand semver and know how to use breaking changes. Of course if a project is just very stable and sticks to 1.x, that‘s great too. I don‘t consider that a negative signal. Purely anecdotally, 3 is the scariest version number to me.

React sets a pretty good example here: react 17 is the most boring release in the world. The react team are not bad API designers that made 17 major mistakes. They may be the most considerate and pleasant API designers in all of frontend, actually.

React Native is on 0.64.4 (?) not because it‘s unfit for production but because they know the level of guarantees they can make about version upgrades is zero.

I've also seen projects on like 124.0.0 just because they don't care about semver and just release major versions every time.

Still a better release numbering scheme than going by year and update.

The Naval Research Lab releases their radar processing algorithms package for geointelligence products by build number. We always got a kick out of a new delivery updating us from nrltools-3872 to nrltools-4923 or something.

It's also easy to get to 124 if you are a library with very few private functions -- in that case almost any change breaks ABI.

yes but didn't react do a big jump? like 0.13 -> 14.0 or such many moons ago. at any rate agree with the point

0.x releases are also major versions according to semver, just pre-stable. So many people were referring to React 0.x releases as "React x" that they just bumped it straight to version x.

Unfortunately, go has broken semver, so all of my go projects now stay at 1.x.y, with x being the "major" version (breaking changes) and y being the "minor" version (non-breaking changes) and the 1 sitting there useless. I suspect that many others do the same, so for go projects the x version field is the one to pay attention to.

Although TBH it's not all bad; all anybody has ever really cared about is "are there breaking changes or not?"

To me it's a signal that if I rely on this software in my own projects, I am signing up for an upgrade treadmill.

Amen.

2 seems to be the final number for business stuff. CustomerReportv2 or UserModel2 or /api/v2/ are wildly more common than 3 IME.

“That major update where we redid the whole API turned out to be so unexpected painful, we’re never doing that again” once for every business

I think it goes something like

1: We made something that we think is good, but we don‘t know if others will and how they will use it. We tested it well in one scenario but not much else.

2. Now we actually understand how people use this and why they like it. We have collected all of their biggest problems and it‘s time to fix them.

3. Everyone loves our thing and it‘s very productive for them. That must mean we‘re geniuses. Let‘s fuck around and change the world.

4, 5, 6… Both we and our users understand that sometimes we need to make a breaking change. They already went through the terrible 2->3 migration so every other upgrade will be fine by comparison.

In an enterprise context there are probably enough layers that keep everyone in check so the step 3 where you run wild with your ideas never happens.

My first thought was along the same lines. Especially for the major version, there's no need to imply there was a failure. Version 1.0 was the right thing at the time. Version 2.0 means something about the requirements or use cases changed in the intervening time, so it's necessary to track that change. Minor and Patch have the same implications, although in my mind a "patch" can also happen when there's just the sort of mistake the can creep in because of human imperfections.

In any case, it doesn't matter except to consumers of the API who need to know the level of backward compatibility.

I wonder if people would be less offended by this if it was "MISTAKES.FEATURES.BUGS".

In American culture (in my experience) everyone takes pride in learning from their mistakes - but no-one likes to think of them as failures.

PAST-MISTAKES.FUTURE-MISTAKES.CURRENT-MISTAKES

Nailed it.

Everything becomes a mistake eventually.

"You[r feature] Either Die[s] A Hero, Or [it] Live[s] Long Enough To See [it]self Become The Villain" ~Harvey Dent [Sorta]

That’s surprisingly applicable. I’ve definitely seen this happen more than a few times.

Hah that's really good.

I'm not offended. I just think it's wrong to paint with such a wide brush. Breaking changes don't always mean that something was a mistake. They often mean a change in direction, and that can happen for a myriad of reasons.

We like more nuance on HN than Twitter seems to.

Seems like it has to do with the word failure more than anything. It is a failure, every time you don’t ship a perfect product it’s a failure of some kind. The iteration process is simply removing failures from a product until you reach feature completeness. I don’t think the difference is that large between a failure and a mistake.

I don't believe that a prior thing which lacks a new advancement means the prior was a mistake or a failure. We're a creative species that strives for improvement. The first running shoe wasn't a mistake nor was it a failure. But the ones I use to run 40 years later sure have improvements.

That’s why I don’t think failure is a good word. But what’s a word to say, “it works but it could be better,” other than failure?

This is definitely true for library code. I don't think the idea holds up for squishier things- moving from version 1.x to 2.x could make the user experience worse, depending on what you prioritize and who's making decisions.

> It is a failure, every time you don’t ship a perfect product it’s a failure of some kind.

It's impossible to ship a perfect product. So perhaps we shouldn't use "failure" to denote not doing the impossible, and reserve it for cases where "success" is even possible.

This thread has made me appreciate the Star Trek Kobayashi Maru exercise in new ways. People _really_ don't like being told that they've failed.

Perhaps the approach of vapid, pessimistic short-takes doesn't play well outside of Twitter, where folks aren't as impressed by blue checks and large followings, and where there isn't a benefit to jockeying for engagement. Based on your comments throughout the threads here, you appear to be overly eager to paint with an overly negative, wide brush that ignores nuance and the multitudes of situations in which your assertion doesn't come close to being true. For instance, adopting an upstream dependency change containing a breaking change, which necessitates releasing a major version in which no notion of failure, mistake, or misstep exists. I'm unsure how you gained such a large following, but your comments aren't at all inspiring or insightful - only somewhat controversial.

It's possible to ship a product that doesn't break though.

You can add new APIs, etc, instead of breaking existing ones. Anytime you do a major rev because your changing an API or removing one, you could also ship new APIs instead and keep the major version the same.

Even if did ship a perfect product, it wouldn’t stay perfect because the world changes.

Which is why I think it is bad semantics to say changing an API is an indication of failure.

In practice, usually it means "we couldn't think of a way to do this without breaking changes even though ways clearly exist".

As I mentioned below, “fail” is an overloaded word and in server another meaning is intended. Longer but more correct: “BREAKING_CHANGES.FEATURES.BUG_FIXES”

You can get everything right and still intentionally introduce a breaking change in a future release.

Maybe the 'offence' is from somebody reading far too much into something?

Will is now suggesting "LEARNING_OPPORTUNITIES.FEATURES.BUGS"

Opengl jumped from 2 to 3 because hardware changed. It doesn't mean the old API failed or was a mistake, it did the job it was intended to do, and then they needed it to do something radically different.

They failed to predict the future hardware.

A failure isn't always a bad thing. Sometimes it's the best thing possible.

Stating that they failed to predict the future hardware implies that they should or could have.

Is this true? Maybe, maybe not, I'm neither a GPU driver write or a hardware writer, but I suspect no software writer in 1997 was going to predict the hardware of 2008.

Predicting the future wasn't the objective. The hardware of that time couldn't have supported OpenGL 3 even if they'd wanted to

Actually they didn't. It was still backwards compatible, so the number change would be unnecessary in semver.

OpenGL 3 is backwards compatible with 2 itself being backwards compatible with 1, etc. (ignoring the whole profiles thing which was a mistake and aside from Apple who went their own way with Metal, everyone else eventually agreed with that) as is 4.

Also OpenGL 1.x didn't map to the underlying hardware even considering SGI, a lot of stuff was done on the CPU. The only time OpenGL matched the underlying hardware was around GeForce 2 and AFAIK that was really matching Nvidia's hardware - before and after that little window, OpenGL was its own abstraction.

But of course OpenGL is a very good example of an API done right (especially before Khronos took over and made a mess out of it): it did a reasonably good prediction for the future while providing a good API for the present (at the time) and even when the underlying hardware changed considerably, it still remains a very useful API with a reasonable mapping and its extension system allows it to take advantage of new hardware features without breaking existing code.

While i do not think Khronos did a good job on OpenGL, at least they did the right thing by making Vulkan a separate API instead of calling it "OpenGL 5", allowing the two APIs to coexist and not break any existing code. After all Vulkan is fine (even if not to my taste, it is unnecessarily oververbose and pretends to be a low level API when it isn't) if you absolutely want the best performance from a hardware abstraction API while OpenGL is still around when you do not need that and want something more user (programmer) friendly instead (though do not get me wrong, depending on what you do, you can extract a lot of performance out of OpenGL, though after some point you may need to switch to Vulkan).

True. Many people get offended when you say the glass is half empty, but nobody gets offended when you say the glass is half full. If I must point out a failure, I will make sure to wink and smile while doing it, which is tough on Twitter.

Is something that can be improved inherently a mistake?

Mistake/Failure both imply an extra level of judgement "Oh, if only you'd worked harder you would have had the right API design the first time and you'd never need a new version".

Sometimes the world changes around an API.

Sometimes there is data that can only be gathered from real world usage.

Sometimes there's new use cases to handle.

If one is desperate for a "fails/mistakes" kind of verb then "BREAKS" (as in "includes breaking changes") might actually hold sway, but then you'd leave out the "major functionality added" scenario for, well, MAJOR.

In short, I think OP's observation is that of a pessimist's.

If not "MAJOR.MINOR.BUG" (which needs no improvement IMO) I'd go with...

TECTONIC.FEATURE.FIX.

Amen. Although, if you're on version 931.59.12, then maybe something is wrong.

Almost an IP address

Haha that should be the line to tell your team - "Ok guys, this is almost an IP address... it's time to move on."

Reply on news.ycombinator.com