How you can tell you made a good library?
-
Last week I did some coding, mostly out of necessity, and created a library that talks to some enterprise monstrosity and makes it possible using scripts instead of the rather cumbersome GUI they have.
Now, it was my third attempt to do this; I had looked at my second attempt at it after a few months of the bliss of not needing to use it, and a few weeks in the hospital, and realized I didn't understand a thing about how it worked at all, and how I was supposed to teach it new tricks.
Then after a few days of sweating, I produced something I could use for the original purpose, and a few others. Throw data into the system? No problem. Find inconsistencies in existing data? 10 minutes of writing a script (and 20 minutes of it working, because the monstrosity is a slow thing). Produce some Excelable statistics? Phew, another 10 minutes.
So, I remember @cartman82 telling about good libraries being written in the least magical way, preferring simple loops to closures and so on. I can add a few more traits of a good library to that:
- You can write an ad-hoc script with it in very short time without needing to refer too much to the source code of the library itself;
- You can use this library for a wide range of purposes with the same, or similar, learning curve.
To exemplify the last point: if you can read and query data with your library in 10 lines code, then bulk-uploading data should also take about 10 lines of code, not much more complicated than that. If bulk-uploading takes, all of a sudden, 200 lines of code, there's something wrong with the library.
I know the library will probably die with me leaving that company, but, well, I can tell that I have learned to do some things properly.
-
@wft said in How you can tell you made a good library?:
You can write an ad-hoc script with it in very short time without needing to refer too much to the source code of the library itself;
s/too much/at all.
If your users need to read the source, you've failed to provide a clean, POLS-obeying API and document it exhaustively.
-
@Maciejasjmj I understand that when you don't need to inquire into how the library does it at all, it's a rather unattainable level of perfection. Thus, not too much.
-
@wft have you ever needed to read the source of, say, a .NET framework component, or Java's however they call their standard library?
It's very much attainable, at least for typical use of the libraries. That most developers these days don't bother, well...
-
I'd say in most cases you should be able to write scripts without looking at the library's source code at all, and without spending an overly long amount of time looking at its documentation either.
-
@wft For an internal library that's only used within the company, I'm willing to forgive a little bit of that stuff.
For an open-source (and obviously a closed-source) library that you're releasing to a third-party, you need to achieve that kind of perfection. I've had libraries in the past which were either documented poorly or even inaccurately, which forced me to find their source on github to figure out what the hell to do. Usually the next thing I'd navigate to in my browser is an alternative library that doesn't require me to do that.
-
@The_Quiet_One said in How you can tell you made a good library?:
For an open-source (and obviously a closed-source) library that you're releasing to a third-party, you need to achieve that kind of perfection.
Well, when you work for a corporation, you have deadlines to do a task. The library was not the task, what I did with it was the task. So I hammered it until it was good enough for me. Of course, it would require 4x more work at least to be in the shape for a release, should I open source it (but I won't, because work for hire and all that jazz). Documentation is a big one. And it has to be good.
-
@Maciejasjmj said in How you can tell you made a good library?:
If your users need to read the source, you've failed to provide a clean, POLS-obeying API and document it exhaustively.
That's compiled lamguage thinking.
Once you get used to effortlessly stepping in and out of vendor source code, you can never go back. Documentation is a nice starting point, but not enough.
-
@cartman82 said in How you can tell you made a good library?:
@Maciejasjmj said in How you can tell you made a good library?:
If your users need to read the source, you've failed to provide a clean, POLS-obeying API and document it exhaustively.
That's compiled lamguage thinking.
Those wacky compiled language folks with their "proper documentation" and "clean APIs". Putting out obtuse crap in JS with the only documentation being a Github README full of buzzwords and the attached source is the 2016 way!
Yeah, fuck that. I can step into .NET source in VS, or into any library with dotPeek, but if I need to do that, you - as a library maintainer - have failed. Do not pass Go.
-
@Maciejasjmj every time I go back to C#, I miss the easy ability to just step into library code, maybe make a temp hack. Especially as you move off the legacy world of .NET 4 and into the brave new future of OWIN, UWP and friends.
-
@cartman82 said in How you can tell you made a good library?:
every time I go back to C#, I miss the easy ability to just step into library code
I literally just told you you can do that. dotPeek is free I think, and it integrates with VS, so "Step Into" works even with outside code. It just decompiles it on the fly, into a pretty readable output.
And even without dotPeek, there's an option buried somewhere under the debug settings to step into .NET code and use the reference source.
-
@Maciejasjmj said in How you can tell you made a good library?:
And even without dotPeek, there's an option buried somewhere under the debug settings to step into .NET code and use the reference source.
Its not the same if it's not fully transparent, and can't make ad hoc changes.
Some code visibility does help, though. Had some experience with that debugging android code.
-
https://godoc.org/github.com/BenLubar/hellstew/emoji
I made a library. Is it good?
-
@wft said in How you can tell you made a good library?:
Well, when you work for a corporation, you have deadlines
@cartman82 said in How you can tell you made a good library?:
That's compiled lamguage thinking.
We are talking about ideals here. What makes a library good. There's always going to be real-world constraints stopping you from achieving perfection, but the closer you get, the better you are.
-
@ben_lubar said in How you can tell you made a good library?:
I made a library. Is it good?
It doesn't document what emoji it supports (or how to extend that). It also doesn't provide a mechanism to control exactly what the replacement HTML is. Finally, I don't see what happens if it finds an emoji in somewhere like the contents of a
<script>
tag, though that might be because I don't know the underlying HTML handling library well.Creditable, but not yet API nirvana.
-
@dkf said in How you can tell you made a good library?:
Finally, I don't see what happens if it finds an emoji in somewhere like the contents of a
<script>
tagIt ignores
<script>
tags, along with a few others: https://github.com/BenLubar/hellstew/blob/6e067d7e265f926681b1dc3e96c2cde7f7a4ca39/emoji/replace.go#L9-L15
-
@ben_lubar said in How you can tell you made a good library?:
It ignores <script> tags, along with a few others:
Ah, but is it documented to do so? :)
Documentation is a funny old thing, since you can often avoid a lot of documenting things when you're exactly following some “well-known” conventions, yet the only way that things really become well-known is by documenting them properly. To be fair, that could be by third-parties.
-
@dkf said in How you can tell you made a good library?:
It doesn't document what emoji it supports (or how to extend that).
It gets the emoji from here:
Which is generated by this:
https://github.com/BenLubar/hellstew/blob/6e067d7e265f926681b1dc3e96c2cde7f7a4ca39/emoji/generate.goWhich gets the data from GitHub's emoji library:
Right now, there's no API to add custom emoji, but I'm thinking it would be nice to have that along with support for image "emoji" like .
Anyway, the demo is here, but it doesn't work in Firefox. Edge and Chrome are ok.
-
@dkf said in How you can tell you made a good library?:
@ben_lubar said in How you can tell you made a good library?:
It ignores <script> tags, along with a few others:
Ah, but is it documented to do so? :)
Documentation is a funny old thing, since you can often avoid a lot of documenting things when you're exactly following some “well-known” conventions, yet the only way that things really become well-known is by documenting them properly. To be fair, that could be by third-parties.
Documentation also means you're required to keep that behavior in the future.
-
@ben_lubar If you document no behavior whatsoever, you've made no promises! Your library is entirely unusable and therefore you don't have to maintain it.
-
@ben_lubar said in How you can tell you made a good library?:
https://godoc.org/github.com/BenLubar/hellstew/emoji
I made a library. Is it good?
Apt repo name.
-
@ben_lubar said in How you can tell you made a good library?:
Documentation also means you're required to keep that behavior in the future.
That's a good thing from the perspective of anyone using the code. While yes, documenting stuff locks you down, it enables others to build on top. And you can do an API migration (as long as you change the major version and warn people that you've done it). They're slow to do, make some people grumble a lot, and you shouldn't do them very often, but it's not impossible.
If your software hasn't had a real release yet, nobody sane will be building on it in the first place. (The JS world isn't sane, of course.)