|
I'm sure you've never seen this "obligatory XKCD"[^] before. 
"These people looked deep within my soul and assigned me a number based on the order in which I joined."
- Homer
|
|
|
|
|
Quote: Should libraries have a standard API and naming convention?
We absolutely need a single standard! Microsoft's standard, Google's standard, Apple's standard, Facebook's standard.
Or if you prefer, 2023 standards, 2024 standards, 2025 standards.... 
|
|
|
|
|
We'll call it MGAF. After a few iterations it can be renamed to MacGyver. Then we'll have come full circle. 
Jeremy Falcon
|
|
|
|
|
Because we don't have a good widely accepted book on naming conventions. The reasons are software engendering is relatively new and shockingly fluid trade. I'm pretty sure the first tribe healers had many different words for constipation back then; in the stone age.
Advertise here – minimum three posts per day are guaranteed.
|
|
|
|
|
It has really only been 80 years or so. I'm sure we'll get there... 
cheers
Chris Maunder
|
|
|
|
|
This has been a discussion point in programming since the first subroutine was written. It will continue forever.
Good luck
To err is human to really elephant it up you need a computer
|
|
|
|
|
Chris Maunder wrote: We're scared to break backwards compatibility so we create new methods to avoid breaking old methods, and overloading functions doesn't always work is or possible
That's always the crux of the situation. The reality is, if you have a lot of users, not every dev is hardcore and wants to spend their entire life always relearning. And to be honest, if you want a family and kids you can't really blame some people. So, there needs to be a sense of familiarity even if something new is introduced. If it's completely different with every major release, you'll find yourself losing users that just want to get their job done and don't care about being an uber geek.
Love or hate PHP, that's the exact reason it was so hard for it to de-crap (if it ever did). It just got too popular too quick. And to keep that... they kept the crap. The original developer even mentioned this. He never expected PHP to get so popular as it did in the beginning. But, once it did it was too late.
Chris Maunder wrote: There are too many ways to do a given task so we present you a bag of parts (eg streams and buffers) and let you mix and match because there's no single "default" way that's practical to provide
So if you want a design an API that's "easier" but the original goal of the first version of the API was to be granular... and let's say you can't change the first version much because of a strict ABI compatibility, then adding helper classes and/or a helper API is what I'd usually do. To your point, it does bloat the codebase. I suppose keeping it a separate helper project would help with that.
If it's a fundamental paradigm shift though, like using AI and qubits to psychically predict winner lottery numbers while retrieving data, that would be a new project for sure.
Chris Maunder wrote: Program flow has changed sufficiently (eg async and promises) that there truly needs to be different methods to cater for this
It's worth mentioning that is this a good thing since CPUs are all about cores now and not just upping raw clock speed. I suppose the design of this would be language dependent though. As far as JavaScript, you can keep pretty much the same API design when it comes to async vs synchronous code.
Chris Maunder wrote: We just like making up new paths for writing the same old code because they suited our headspace at the time
As far as naming standards go, such as REST, it's a good thing in the modern world. Back in the 1960s nobody cared about connected systems. Nowadays, eventually even the desktop will be replied by a merge of web and desktop technologies. Connectivity is king. Being able to crosstalk between different, disconnected systems is way more important. The whole idea behind web 3.0 (not web3) and web 4.0 concepts require this.
So yeah, it's more involved to have to learn a standard, but any industry gets more involved as it grows. This one is no different. And have some conventions not only helps with discoverability if documentation is lacking, it can help with the actual coding aspect to because you'll get some idea of what's what from a disconnected system.
Jeremy Falcon
|
|
|
|
|
Jeremy Falcon wrote: Nowadays, eventually even the desktop will be replied by a merge of web and desktop technologies.
Desktop computers? I doubt that. Been tried multiple times using different ways. None of them had any acceptance. Timesharing computers in the 70s was widely used but only because the cost of individual computers was so high.
|
|
|
|
|
I'm not interested in your thoughts. You continue to reply to me after we've established you're just going to argue 90% of the time. Again... I would block you if I could. You can't take a hint and just go away.
Jeremy Falcon
|
|
|
|
|
Chris Maunder wrote: any time you get data from a source (uploaded file, network stream, from database) you call it "Get"
Conflicts with standard class access for attributes - getter and setter
Chris Maunder wrote: any time you need to append data, you call Append, and also override the + operator.
Absolutely not - never do that.
Overriding operators should only occur in very limited circumstances. Used to be I would claim that it might work for vector addition but I am not even sure I would support that anymore.
Chris Maunder wrote: I just want to save the file to disk.
I don't see your point. Streams have never been limited to just that. Moving data has always had more potential than that. Certainly true now. And also true long ago.
Adding distinct methods for every potential movement of data would be a bad idea.
Chris Maunder wrote: We're scared to break backwards compatibility
Yes please. More of that. I cringe, with good reason, every time I see someone refactor code because they think they are making it better. I have seen two different production problems show up in just the last 6 months because of that.
That doesn't include the ones I stopped from happening because I saw the code before hand and was able to point out the enterprise impact before it rolled out.
Chris Maunder wrote: I think we as an industry need a big refactoring.
People buy hammers but they do so to build tables, fences, houses, and skyscrapers.
Software development is a hammer. It is not the product/service. The sales people do not care if the healthcare site uses two API methods with different names but which do the same thing. And the customers definitely do not.
Sure it increases maintenance costs. But so does a full enterprise refactor.
|
|
|
|
|
Different windmills, same tilting...
Around 1880, my great-great grandfather W E Hearn[^] set out to codify the laws of the State of Victoria. He was equally successful.
Quote: However, the codification was never adopted since "although praised in Parliament, [it] was regarded as too abstract by practising lawyers."
Software rusts. Simon Stephenson, ca 1994. So does this signature. me, 2012
|
|
|
|
|
I don't expect the industry to standardize; this can even be undesirable. Standards can be dominated by big players who've already more or less aligned to the standard they're pushing. This gives them an advantage and makes it difficult for others to differentiate. But I expect each library to standardize internally instead of running amok with inconsistent naming or ways of doing something, although I can see the latter happening when intended for a broad range of applications.
Each of the four reasons you listed for a lack of standardization plays a role.
Breaking changes are a pet peeve. To me, a breaking change is something that requires a user to redesign their software, which is definitely something to avoid. However, simply changing a function name or its signature, and providing release notes so that users can easily convert to the new interface, shouldn't be considered a breaking change. But whiners will whine. Fine, so stay on the old release if you expect to do no work to move to the new one. Good libraries and frameworks maintain a low surface-to-volume ratio.
I think your #2 and #3 (both the result of multiple ways of doing something) are excusable in a library that supports a broad range of applications. But a library focused on specific types of applications should be more opinionated, settling on a standard way to do each thing in order to improve code reuse and interoperability between the applications that use it.
#4, and #2 and #3 when unwarranted, are what a former colleague called superfluous diversity. This is a dead giveaway that the system lacks what Brooks called conceptual integrity. It was almost certainly developed without proper design and code reviews or software architects to steer it on a consistent path.
|
|
|
|
|
<i>"However, simply changing a function name or its signature, and providing release notes so that users can easily convert to the new interface, shouldn't be considered a breaking change."</i>
If not, then what would be considered a breaking change? An undocumented one?
|
|
|
|
|
Sure, an undocumented change. Or one that forces part of an application to be redesigned.
|
|
|
|
|
As a developer and maintainer of both old lightly maintained code and packages that are effected by breaking changes I can't agree. Any change that breaks existing code is a breaking change, regardless of how broad the changes to support it are.
An undocumented breaking change and a documented breaking change just differ in how likely it is that you will notice it ahead of time. If you are actively monitoring the source repos, you will catch it whether it makes release notes or not, and makingthe release notes doesn't mean it gets caught before release... especially with automagic repo updates upstream that sneak changes in that suddenly break docker or nix builds.
As a package maintainer, any change that requires the customer to edit their code at all is treated as a breaking change. We work very hard to make sure that old code continues to build without modification. If new code won't work on older versions, like we've added an API call but haven't changed any, or changed the meaning of a parameter in a backwards-compatible way, that's not a breaking change. If we've changed an existing API call so code has to be modified, that's a breaking change.
-- modified 14-Jun-23 12:00pm.
|
|
|
|
|
Good answer.
Especially in the context of a 'library'.
I certainly appreciate that share ware developers at least seem to adhere to the convention that a major number change in the version means something will break.
But it certainly doesn't make me happy knowing that I will need to modify my existing code just to get access to some new feature.
I always expect the following for a new version.
1. It will take a substantial amount of time. Certainly weeks.
2. Requires a full regression test.
3. Less experienced developers think they will be able to go up a major version just by dropping in the library.
Even worse if I need to go up more than one major version.
1. It will require months.
2. I might need to go up one version and then go up the next version because attempting it at one go is just too likely to lead to production breakage due to unexpected problems. There could even be impacts on the architecture itself.
|
|
|
|
|
Ideally, with semantic versioning, yeh, a major version kind of implies there are breaking changes somewhere. But of course semantic versioning is a standard and you know what XKCD says about standards.
Aside: shareware is something completely different.
|
|
|
|
|
Greg Utas wrote: I don't expect the industry to standardize; this can even be undesirable. Standards can be dominated by big players
Even standards don't work.
That is why there is HTML versions 1 to 5. And sub versions.
Then SSL and TLS with multiple versions of each. Not to mention that secure IP has been proposed but certainly not adopted.
SMTP is simple but then if you want to add an attachment.
SNMP says a lot about how to get an interrupt but nothing about what it should be. So one cannot program to handle just interrupts since different devices for the same failure will send an interrupt or not.
The Java Specification still has the same BNF bugs as when it was first published. And those were formally reported back then. Fixing those doesn't change the language since one must implement it the way it would be fixed anyways.
Hungarian notation was invented to deal with specifically with type less parameter checking in C but that seems to escape the notice of adherents even though the originator pointed that out. Nor was there even really a 'standard' once one got beyond very basic types.
In the following look at the people who don't like this one.
Hungarian notation - Wikipedia[^]
|
|
|
|
|
as you know obtaining the status of a C++ standard library stream requires invoking rdstate . i do not know what the rd stands for . is it per-chance "read" . the set in setstate is a dead giveaway but rd ? who knows . maybe it is returndastate
|
|
|
|
|
Chris Maunder wrote: Open a filestream, call file.CopyToAsync to the stream and close the stream
Well, CopyToAsync is a stream method. A stream can be for any purpose, both the source and destination. So to use this for your example is a bit unfair. Opening a FileStream is the destination to move the data to.
FileStream stream = File.OpenWrite(__filename__);
Graeme
"I fear not the man who has practiced ten thousand kicks one time, but I fear the man that has practiced one kick ten thousand times!" - Bruce Lee
|
|
|
|
|
There are vast difference between programming languages and runtime environments. Take C# and C++, that are not even that far apart. In C++ a class method is called differently than a instance method. In C# there is no difference. In C++ there is a difference between an instance and a pointer to an instance, in C# originally not, but now we have things like ref. And in a procedural language, file.saveas() is not even possible, it would be saveas(file). In other words, nice thought maybe, but not practically possible.
In addition, who is going to enforce this? Will we get a library API police? I hope not.
Maybe the problem is in the moving around of code, and you should have the functional bits in just one place. When I run in to things like this I ask myself "what do I need to do different to not have this problem". Just a thought.
|
|
|
|
|
Plus: How do you make a standard for something you haven't thought of yet? What if I have an idea which doesn't fit the model of standards? More importantly, what if the model of standards restricts my thinking so that I don't have the idea?
|
|
|
|
|
The four file-reading functions you list do different things. It is less confusing to name them different things than it is to figure out how to overload the name for different kinds of file-reading.
There are different pairs of English words you could use (get/set, get/put, load/save, read/write) with little reason to pick one set over another.
And while we're being English-centric, shouldn't an API standard support multiple human languages and character sets? Does that sound like too much? Well, then no standardization for you.
Three of your four reasons there are multiple names for things (compatibility, bag-of-parts, program-flow) are actually good reasons why interface names are not consistent. We have to predict the future to pick the perfect name, and we're no good at that.
I welcome your bold solution to these problems, but don't expect to hear back soon.
|
|
|
|
|
SeattleC++ wrote: There are different pairs of English words you could use (get/set, get/put, load/save, read/write) with little reason to pick one set over another.
You're reminding me of PowerShell, which has (but does not enforce) the use of a specific set of "approved" verbs as the prefix to any function name. MS itself has been pretty good at sticking with it, but I suspect not many people do.
|
|
|
|
|
I have to conclude also that standardizing programming is an exercise in futility but at least, in a slightly more optimistic way, computer archaeologists of the future have a treasure trove of the different ways we were thinking (of course some will think...how silly, with the Vulkan API, everything was eventually perfect, etc.,etc.)
Not saying we're documenting our own stubbornness (or stupidity, *cough* cobol *cough*) but nothing is lost if we have a few dozen ways to execute or express what saving a bunch of 1's and 0's actually is (and I can just hear the voices of dead engineers whispering how magnetic memory cores worked)
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
