Should libraries have a standard API and naming convention?
-
From my perspective: There is no other profession, that I personally know of, where there is a pool of vastly differing opinions on how to do things and how things should be, than software development and developers. We have standardized music, medical, and most science fields, but software engineering/development is lacking big time. So, I agree with you that we as an industry should standardize as much as we can (not just APIs), but then who gets to be the king on what the standards are? You? Me? Jeff down the street? What if I don't like your standards? back to square one. IMHO, this is an exercise in futility.
I guess I misread some of that post then. Coming from the web side, we do have standards in naming conventions. We just didn't invite Jeff to the meeting. :laugh:
Jeremy Falcon
-
From my perspective: There is no other profession, that I personally know of, where there is a pool of vastly differing opinions on how to do things and how things should be, than software development and developers. We have standardized music, medical, and most science fields, but software engineering/development is lacking big time. So, I agree with you that we as an industry should standardize as much as we can (not just APIs), but then who gets to be the king on what the standards are? You? Me? Jeff down the street? What if I don't like your standards? back to square one. IMHO, this is an exercise in futility.
That's the beauty of Standards: there are so many to choose from.
cheers Chris Maunder
-
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
-
I'm in the process of moving some code in between Javascript, .NET Core 5, .NET 7 with detours around Razor and Blazor. The code changes between them are doing my head in. Just reading a file from the browser seems to have 6 different ways, all subtly different, all similarly named. I understand that changes in underlying architecture means that one method won't necessarily translate to another, but surely there are some core things that we, as an industry, could standardise. For example: You have an object, for instance a file. Or a tensor. Or a string. - any time you get data from a source (uploaded file, network stream, from database) you call it "Get" - any time you save data to storage you call it "Save" - any time you need to append data, you call Append, and also override the + operator. The thing that's getting me is I just want to save an uploaded file. A quick check shows I can 1. Call file.SaveAs to save the file 2. Open a filestream, call file.CopyToAsync to the stream and close the stream 3. Read the file's InputStream into a buffer and call File.WriteAllBytes to save the buffer 4. Same as 2, but using CopyTo instead of CopyToAsync I'm sure there are more. I just want to save the file to disk. So I'm wondering, since I've not actually taken the time to read up on this, if this happens because 1. 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 2. 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 3. Program flow has changed sufficiently (eg async and promises) that there truly needs to be different methods to cater for this 4. We just like making up new paths for writing the same old code because they suited our headspace at the time It seems a massive waste of cycles. I think we as an industry need a big refactoring.
cheers Chris Maunder
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.
-
From my perspective: There is no other profession, that I personally know of, where there is a pool of vastly differing opinions on how to do things and how things should be, than software development and developers. We have standardized music, medical, and most science fields, but software engineering/development is lacking big time. So, I agree with you that we as an industry should standardize as much as we can (not just APIs), but then who gets to be the king on what the standards are? You? Me? Jeff down the street? What if I don't like your standards? back to square one. IMHO, this is an exercise in futility.
Slacker007 wrote:
We have standardized music, medical, and most science fields, but software engineering/development is lacking big time
No. Humans are messy. You do know that Ed Sheeran just won a civil case for copyright infringement based on, presumably, one of those 'standards' of the music industry? So certainly not settled for some. You do know that there are license medical doctors that are prescribing CAM (Complementary Alternative Medicine) medicine? You know that every cancer hospital except for one has a CAM center? You do know that people were comparing the way the Mumps vaccine was originally researched and even what it does to how COVID mRNA (and all mRNA) vaccine was researched? It took 30 years for Texas to finally remove the license of a medical doctor who has been prompting and profiting from a medical therapy that was disproved almost at the very time it was first proposed? Not to mention what happened with Aducanumab? Not sure what you mean by "science" but in India you can get a MBA in Astrology (yes spelled correctly) at most or perhaps all universities? I think one offers a Masters of Science as well. Of course in the US 'talk therapy' is still offered by psychologists and even psychiatrists. Not to mention a slew of things like court order anger management. And the DSM (Diagnostic and Statistical Manual of Mental Disorders) is for the most part full of definitions that are nothing more that descriptions of how people describe that the 'feel'. Thus no actual objective criteria. The most recent release was disputed by at least some due to it continuing to do that and even expanding on those sorts of definitions. The number of pay per publish 'science' publications are probably expanding. And it seems to be a trend to now realize that the standard for looking for errors which can lead to false positives in studies is finally (like in the last couple of years) is being revised to be more strict. This came about because of a large effort to try to reproduce results for studies in reputable (not pay per publish) magazines which fail to reproduce the results of the original study?
-
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 bec
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 in the process of moving some code in between Javascript, .NET Core 5, .NET 7 with detours around Razor and Blazor. The code changes between them are doing my head in. Just reading a file from the browser seems to have 6 different ways, all subtly different, all similarly named. I understand that changes in underlying architecture means that one method won't necessarily translate to another, but surely there are some core things that we, as an industry, could standardise. For example: You have an object, for instance a file. Or a tensor. Or a string. - any time you get data from a source (uploaded file, network stream, from database) you call it "Get" - any time you save data to storage you call it "Save" - any time you need to append data, you call Append, and also override the + operator. The thing that's getting me is I just want to save an uploaded file. A quick check shows I can 1. Call file.SaveAs to save the file 2. Open a filestream, call file.CopyToAsync to the stream and close the stream 3. Read the file's InputStream into a buffer and call File.WriteAllBytes to save the buffer 4. Same as 2, but using CopyTo instead of CopyToAsync I'm sure there are more. I just want to save the file to disk. So I'm wondering, since I've not actually taken the time to read up on this, if this happens because 1. 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 2. 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 3. Program flow has changed sufficiently (eg async and promises) that there truly needs to be different methods to cater for this 4. We just like making up new paths for writing the same old code because they suited our headspace at the time It seems a massive waste of cycles. I think we as an industry need a big refactoring.
cheers Chris Maunder
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'm in the process of moving some code in between Javascript, .NET Core 5, .NET 7 with detours around Razor and Blazor. The code changes between them are doing my head in. Just reading a file from the browser seems to have 6 different ways, all subtly different, all similarly named. I understand that changes in underlying architecture means that one method won't necessarily translate to another, but surely there are some core things that we, as an industry, could standardise. For example: You have an object, for instance a file. Or a tensor. Or a string. - any time you get data from a source (uploaded file, network stream, from database) you call it "Get" - any time you save data to storage you call it "Save" - any time you need to append data, you call Append, and also override the + operator. The thing that's getting me is I just want to save an uploaded file. A quick check shows I can 1. Call file.SaveAs to save the file 2. Open a filestream, call file.CopyToAsync to the stream and close the stream 3. Read the file's InputStream into a buffer and call File.WriteAllBytes to save the buffer 4. Same as 2, but using CopyTo instead of CopyToAsync I'm sure there are more. I just want to save the file to disk. So I'm wondering, since I've not actually taken the time to read up on this, if this happens because 1. 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 2. 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 3. Program flow has changed sufficiently (eg async and promises) that there truly needs to be different methods to cater for this 4. We just like making up new paths for writing the same old code because they suited our headspace at the time It seems a massive waste of cycles. I think we as an industry need a big refactoring.
cheers Chris Maunder
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.
Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing. -
I'm in the process of moving some code in between Javascript, .NET Core 5, .NET 7 with detours around Razor and Blazor. The code changes between them are doing my head in. Just reading a file from the browser seems to have 6 different ways, all subtly different, all similarly named. I understand that changes in underlying architecture means that one method won't necessarily translate to another, but surely there are some core things that we, as an industry, could standardise. For example: You have an object, for instance a file. Or a tensor. Or a string. - any time you get data from a source (uploaded file, network stream, from database) you call it "Get" - any time you save data to storage you call it "Save" - any time you need to append data, you call Append, and also override the + operator. The thing that's getting me is I just want to save an uploaded file. A quick check shows I can 1. Call file.SaveAs to save the file 2. Open a filestream, call file.CopyToAsync to the stream and close the stream 3. Read the file's InputStream into a buffer and call File.WriteAllBytes to save the buffer 4. Same as 2, but using CopyTo instead of CopyToAsync I'm sure there are more. I just want to save the file to disk. So I'm wondering, since I've not actually taken the time to read up on this, if this happens because 1. 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 2. 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 3. Program flow has changed sufficiently (eg async and promises) that there truly needs to be different methods to cater for this 4. We just like making up new paths for writing the same old code because they suited our headspace at the time It seems a massive waste of cycles. I think we as an industry need a big refactoring.
cheers Chris Maunder
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 insetstateis a dead giveaway but rd ? who knows . maybe it is returnd_a_state -
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.
Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing."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." If not, then what would be considered a breaking change? An undocumented one?
-
I'm in the process of moving some code in between Javascript, .NET Core 5, .NET 7 with detours around Razor and Blazor. The code changes between them are doing my head in. Just reading a file from the browser seems to have 6 different ways, all subtly different, all similarly named. I understand that changes in underlying architecture means that one method won't necessarily translate to another, but surely there are some core things that we, as an industry, could standardise. For example: You have an object, for instance a file. Or a tensor. Or a string. - any time you get data from a source (uploaded file, network stream, from database) you call it "Get" - any time you save data to storage you call it "Save" - any time you need to append data, you call Append, and also override the + operator. The thing that's getting me is I just want to save an uploaded file. A quick check shows I can 1. Call file.SaveAs to save the file 2. Open a filestream, call file.CopyToAsync to the stream and close the stream 3. Read the file's InputStream into a buffer and call File.WriteAllBytes to save the buffer 4. Same as 2, but using CopyTo instead of CopyToAsync I'm sure there are more. I just want to save the file to disk. So I'm wondering, since I've not actually taken the time to read up on this, if this happens because 1. 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 2. 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 3. Program flow has changed sufficiently (eg async and promises) that there truly needs to be different methods to cater for this 4. We just like making up new paths for writing the same old code because they suited our headspace at the time It seems a massive waste of cycles. I think we as an industry need a big refactoring.
cheers Chris Maunder
Chris Maunder wrote:
Open a filestream, call file.CopyToAsync to the stream and close the stream
Well,
CopyToAsyncis 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
-
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
-
That's the beauty of Standards: there are so many to choose from.
cheers Chris Maunder
Obligatory xkcd: Standards[^]
Software Zen:
delete this; -
I'm in the process of moving some code in between Javascript, .NET Core 5, .NET 7 with detours around Razor and Blazor. The code changes between them are doing my head in. Just reading a file from the browser seems to have 6 different ways, all subtly different, all similarly named. I understand that changes in underlying architecture means that one method won't necessarily translate to another, but surely there are some core things that we, as an industry, could standardise. For example: You have an object, for instance a file. Or a tensor. Or a string. - any time you get data from a source (uploaded file, network stream, from database) you call it "Get" - any time you save data to storage you call it "Save" - any time you need to append data, you call Append, and also override the + operator. The thing that's getting me is I just want to save an uploaded file. A quick check shows I can 1. Call file.SaveAs to save the file 2. Open a filestream, call file.CopyToAsync to the stream and close the stream 3. Read the file's InputStream into a buffer and call File.WriteAllBytes to save the buffer 4. Same as 2, but using CopyTo instead of CopyToAsync I'm sure there are more. I just want to save the file to disk. So I'm wondering, since I've not actually taken the time to read up on this, if this happens because 1. 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 2. 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 3. Program flow has changed sufficiently (eg async and promises) that there truly needs to be different methods to cater for this 4. We just like making up new paths for writing the same old code because they suited our headspace at the time It seems a massive waste of cycles. I think we as an industry need a big refactoring.
cheers Chris Maunder
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.
-
"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." 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.
Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing. -
I'm in the process of moving some code in between Javascript, .NET Core 5, .NET 7 with detours around Razor and Blazor. The code changes between them are doing my head in. Just reading a file from the browser seems to have 6 different ways, all subtly different, all similarly named. I understand that changes in underlying architecture means that one method won't necessarily translate to another, but surely there are some core things that we, as an industry, could standardise. For example: You have an object, for instance a file. Or a tensor. Or a string. - any time you get data from a source (uploaded file, network stream, from database) you call it "Get" - any time you save data to storage you call it "Save" - any time you need to append data, you call Append, and also override the + operator. The thing that's getting me is I just want to save an uploaded file. A quick check shows I can 1. Call file.SaveAs to save the file 2. Open a filestream, call file.CopyToAsync to the stream and close the stream 3. Read the file's InputStream into a buffer and call File.WriteAllBytes to save the buffer 4. Same as 2, but using CopyTo instead of CopyToAsync I'm sure there are more. I just want to save the file to disk. So I'm wondering, since I've not actually taken the time to read up on this, if this happens because 1. 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 2. 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 3. Program flow has changed sufficiently (eg async and promises) that there truly needs to be different methods to cater for this 4. We just like making up new paths for writing the same old code because they suited our headspace at the time It seems a massive waste of cycles. I think we as an industry need a big refactoring.
cheers Chris Maunder
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.
-
Sure, an undocumented change. Or one that forces part of an application to be redesigned.
Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing.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.
-
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.
Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing.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[^]
-
I'm in the process of moving some code in between Javascript, .NET Core 5, .NET 7 with detours around Razor and Blazor. The code changes between them are doing my head in. Just reading a file from the browser seems to have 6 different ways, all subtly different, all similarly named. I understand that changes in underlying architecture means that one method won't necessarily translate to another, but surely there are some core things that we, as an industry, could standardise. For example: You have an object, for instance a file. Or a tensor. Or a string. - any time you get data from a source (uploaded file, network stream, from database) you call it "Get" - any time you save data to storage you call it "Save" - any time you need to append data, you call Append, and also override the + operator. The thing that's getting me is I just want to save an uploaded file. A quick check shows I can 1. Call file.SaveAs to save the file 2. Open a filestream, call file.CopyToAsync to the stream and close the stream 3. Read the file's InputStream into a buffer and call File.WriteAllBytes to save the buffer 4. Same as 2, but using CopyTo instead of CopyToAsync I'm sure there are more. I just want to save the file to disk. So I'm wondering, since I've not actually taken the time to read up on this, if this happens because 1. 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 2. 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 3. Program flow has changed sufficiently (eg async and promises) that there truly needs to be different methods to cater for this 4. We just like making up new paths for writing the same old code because they suited our headspace at the time It seems a massive waste of cycles. I think we as an industry need a big refactoring.
cheers Chris Maunder
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)
-
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.
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.
