6 ms·

Leaves the following interesting question: If the developer interface was elegant, and the library itself ran very well without any errors, is anything actuall

by RyanZAG 14y ago

Leaves the following interesting question: If the developer interface was elegant, and the library itself ran very well without any errors, is anything actually gained by making the internal code elegant? What happens if the new version, while more elegant internally, has a new complex bug in it (such as a race condition, that only triggers once every billion requests)? Still worthwhile to fix up the inelegant code that was working correctly? (Disclaimer: I feel it's better to clean it up regardless, but I have a feeling a study would show something different in terms of lost productivity...)

kenneth_reitz 14y ago
It does surface to the lower-level user interfaces, as shown in the blog post's connection adapter example. For advanced users, these changes will mean the world. The new code is also much easier to debug and pleasure to work with. Bugs will be significantly easier to fix :)
nailer 14y ago
> What happens if the new version, while more elegant internally, has a new complex bug in it (such as a race condition, that only triggers once every billion requests)? Still worthwhile to fix up the inelegant code that was working correctly? Then it's easier to find. All software has bugs, readability is one important part of fixing them.
deleted 14y ago
[deleted]
dalke 14y ago
The "developer interface" includes at least three different parts: the API calls, the calling sequence, and the validity of the results. That last part is borderline. Some wouldn't call it part of the interface, but I do, because if there are problems then interface users end up wrapping the interface with another interface to work around those problems. I therefore argue that the "more elegant but buggier" internals don't have the same interface, even if the API calls look the same. As to why it should be more elegant? There are at least four parts here . How does the developer, or any interface user, review the code to see if there is a complex bug inside? That is, your scenario about the bug in the elegant code also applies to the inelegant. And how easy is it to carry out extensions to the project in the old code base vs. the new, even if those new features aren't yet implemented? Third, the type of person who strives for an elegant interface also probably strives for elegant internals. Fourth, there are people who don't like closed boxes, and want to understand some of the insides of a package before they use it. If the insides don't look good, then they might be adverse to using it. A term for the negative aspects of this tendency to clean up internal code is called "gold plating." A positive term is "technical debt", as in the inelegant code incurs a debt which must be paid off in the future by cleaning up the code.
mahmoudimus 14y ago
Testing becomes immensely easier. One of my main gripes with requests was that it had a fantastic API but had very unpleasant internals that made it complicated to test and mock http responses. If this is no longer the case, then this indeed is a fantastic change - looking forward to diving in soon.
sophacles 14y ago
I've never used an open source library where I didn't end up having a question of "how exactly does this work?" (or related "If I do this thing, am I being redundant or interfering with normal operation?". Even with good docs. Requests is a good example of this, I didn't really fully understand what details were and were not kept in their sessions and what I needed to do w.r.t them and some testing I was doing (using requests, not on the lib itself). So I went code spelunking. I didn't think the code was bad to begin with, but if the code is cleaned up, and it would be even easier to do this, kudos on them. They made a future me or someone like me more productive!
ak217 14y ago
It's a little bit naive to ask that question, isn't it? The decision to refactor internals is always related to how much technical debt the developers feel the project has incurred, and how much easier they think it will be to develop in the new codebase. So every rewrite is a subjective call, where future ease of development and attracting/on-boarding new developers is traded off against short-term lost productivity and potential for bugs, incomplete rewrites, and dropped support.

by RyanZAG 14y ago

kenneth_reitz 14y ago

It does surface to the lower-level user interfaces, as shown in the blog post's connection adapter example. For advanced users, these changes will mean the world. The new code is also much easier to debug and pleasure to work with. Bugs will be significantly easier to fix :)

nailer 14y ago

> What happens if the new version, while more elegant internally, has a new complex bug in it (such as a race condition, that only triggers once every billion requests)? Still worthwhile to fix up the inelegant code that was working correctly? Then it's easier to find. All software has bugs, readability is one important part of fixing them.

deleted 14y ago

[deleted]

dalke 14y ago

The "developer interface" includes at least three different parts: the API calls, the calling sequence, and the validity of the results. That last part is borderline. Some wouldn't call it part of the interface, but I do, because if there are problems then interface users end up wrapping the interface with another interface to work around those problems. I therefore argue that the "more elegant but buggier" internals don't have the same interface, even if the API calls look the same. As to why it should be more elegant? There are at least four parts here . How does the developer, or any interface user, review the code to see if there is a complex bug inside? That is, your scenario about the bug in the elegant code also applies to the inelegant. And how easy is it to carry out extensions to the project in the old code base vs. the new, even if those new features aren't yet implemented? Third, the type of person who strives for an elegant interface also probably strives for elegant internals. Fourth, there are people who don't like closed boxes, and want to understand some of the insides of a package before they use it. If the insides don't look good, then they might be adverse to using it. A term for the negative aspects of this tendency to clean up internal code is called "gold plating." A positive term is "technical debt", as in the inelegant code incurs a debt which must be paid off in the future by cleaning up the code.

mahmoudimus 14y ago

Testing becomes immensely easier. One of my main gripes with requests was that it had a fantastic API but had very unpleasant internals that made it complicated to test and mock http responses. If this is no longer the case, then this indeed is a fantastic change - looking forward to diving in soon.

sophacles 14y ago

I've never used an open source library where I didn't end up having a question of "how exactly does this work?" (or related "If I do this thing, am I being redundant or interfering with normal operation?". Even with good docs. Requests is a good example of this, I didn't really fully understand what details were and were not kept in their sessions and what I needed to do w.r.t them and some testing I was doing (using requests, not on the lib itself). So I went code spelunking. I didn't think the code was bad to begin with, but if the code is cleaned up, and it would be even easier to do this, kudos on them. They made a future me or someone like me more productive!

ak217 14y ago

It's a little bit naive to ask that question, isn't it? The decision to refactor internals is always related to how much technical debt the developers feel the project has incurred, and how much easier they think it will be to develop in the new codebase. So every rewrite is a subjective call, where future ease of development and attracting/on-boarding new developers is traded off against short-term lost productivity and potential for bugs, incomplete rewrites, and dropped support.