Hacker News Reader

Comment by vortico | Hacker News Reader

The entire API is 1100 lines. https://github.com/andlabs/libui/blob/master/ui.h You don't need a separate documentation for that. In fact, most functions have sufficient docstrings if their names don't fully describe their function.

Your hostility toward an MIT licensed project is what is ruining the open-contribution model of developing software. In 2005, it was "Hey, this looks great, want me to write up a documentation?" Now it's "Not up to my standards, it's a joke." Absolutely disgusting behavior that is becoming gradually more common.

View on HN

I got to the first function in the API:

    _UI_EXTERN const char *uiInit(uiInitOptions *options);

uiInitOptions is a struct that contains a single size_t Size. What's it the size of? Can I pass a NULL pointer? Does this function take ownership of the pointer, and if so, does it need to be allocated with malloc? If not, when can I free it - can I use a pointer onto my stack? Why does it take a non-const pointer - does the size (of whatever) change? What's the string that's returned? What's the lifetime of the string that's returned? Can another thread call uiInit, or does that break everything horribly? Or does it only break horribly if you don't copy the returned string first?

You don't need documentation, sure. But it's a good way to get users of the library that make wild assumptions so that you can no longer make reasonable upgrades to the library without breaking them, and that makes nobody (neither the library author, who wants people to use it, nor the users themselves, nor end users) happy.

Great! If you can answer those questions, send a pull request to add it to the docstring. You've spent some time thinking of those questions, so you'd write a very complete docstring. Complaining will not solve the issue. Sending a PR will solve it. This is what I was saying above. I am attempting to orient people into the "open-contribution" community, where we share the opinion that free software is NOT free to produce. Someone must do the things you are suggesting at some point if they are to exist, and who better than yourself?

With regards to your last paragraph, a common misconception is that a "payment" of open-source software is number of users. That would be true for proprietary software where payment = number of users * price, but for open-source software the developers couldn't care less (except maybe superficially, but this mental reward is insignificant for the long-term motivation for a project). They want to make a library that solves their own problems and is stable. They allow people to help improve the library in exchange for releasing it for their unrestricted use. Otherwise, there is little motivation to release it. When I find a new library that solves a problem in an interesting way, I learn using whatever is available (existing documentation, headers, source, and examples) and write down the difficult parts. The price I pay for using the software is to send my notes back to the developers in a polished, organized form that is consistent with their existing documentation. Then, no one needs to repeat what I've done in the future.

While I agree with the general thrust of what you're saying (people should contribute far more to the free software they use rather than be angry with maintainers for not solving every issue under the sun -- and having more users is no substitute for having a few passionate external contributors), this is a fairly hostile way of trying to on-board people to a project.

Not to mention that the developers that wrote the project in the first place are in a much better position to write documentation than anyone else (in the past I've had to review documentation from external contributors and I'm pretty sure it would've been phenomenally faster if I'd just written it in the first place -- it isn't their fault, it's just that I know the code and its history much better than them because I've maintained it).

I agree that it's a somewhat hostile way to invite people to a project, but 1) I highly doubt that dropping a cheerful invite will have any convincing power other than someone replying "yeah, I should do that" and then promptly forgetting it, and 2) some scolding was needed. :)

Your second point is a good one, but the developers are in a better position to write actual features and fix bugs than anyone else, and since documentation is more public-facing than source code, it's actually a better choice if someone wants to contribute anything at all, so the primary developers can spend their time more wisely. I certainly know the "phenomenally faster if I'd just written it in the first place" effect well, which is why I recommend to contributers to not do drive-by contributions but spend a good week writing notes while they use the library, and then convert to high-quality documentation, effectively adopting a section like you would with a community garden. Quality over quantity. And if the documentation attempt is low quality, it's still a much nicer way to prod the developer to write some documentation, so he/she can use it to define their quality standards or as a possible outline.

> some scolding was needed

Was it, really? I think the parent comments did a good job at pointing out a potential, actionable, flaw in this project. That doesn't mean that they should be "scolded" for pointing it out or that they themselves need to fix it.

There are times when people report an issue to an open source project and the response is "You should fix it yourself".

Open source contribution happens when the contributor has invested themself in the project and wants to maintain the relationship. Perhaps the requester is evaluating multiple packages and wants to inform the project why they're going with another one instead. Maybe they got to the point in their evaluation that they're ready to commit only to discover a critical issue hidden in the (lack of) documentation.

It also comes off as hostile since implies that the requester's time is less valuable than the project maintainer's. Perhaps the requester is busy contributing to other open source projects. Perhaps the requester only has time right now to use the software, but has the goal of contributing in the future.

The project's maintainer's responsibility is maintaining the software, presumably because of some personal interest. Reporting and even expecting them to fix issues is absolutely normal.

>implies that the requester's time is less valuable than the project maintainer's

It is. In large projects, there are relatively few maintainers responsible for evaluating the requests, reports and code from lots of people. They're scarce resources.

https://www.youtube.com/watch?v=fMeH7wqOwXA https://www.slideshare.net/linaroorg/maintainer

I find if you maintain an open source project as if your users were customers, things tend to go pretty smooth.

Can you explain how you found that?

By trying it, and realizing afterwards that nothing bad happened as a consequence.

The main benefit is that it forces one to try to be professional and consistent, and to avoid being flippant, cryptic, didactic, and condescending.

Keep in mind that cutting customers loose is a natural part of the game, too. If someone demands to get a Big Mac at Chipotle there's no law that says they get to block the line for eternity.

Smooth for whom? Not the one beholden to a bunch of non-paying "customers" I'd wager.

What is the bad thing you posit would happen when a bunch of non-paying "customers" are treated in a professional manner?

Some people just want to use a library. Not everyone wants to build a library. When evaluating a candidate library, it’s perfectly reasonable to look at things like documentation completeness. “Don’t discuss weaknesses; fix them” isn’t helpful or constructive. There is no moral commandment to pretend all open source libraries are without flaws.

geofft could just ignore the library completely without giving his valuable opinions on the kinds of things that should be specified in a reference document. That isn't complaining at all. Maybe the author really has no clue on what information to put into an API document; geofft's comment provides stimulating ideas.

geofft doesn't have an "issue" because he's not using the library; he can avoid the non-documentation problem for himself quite adequately by ignoring the library and moving to a different one.

> If you can answer those questions,

No you can't. You can only reverse engineer what the code does, not what the programmer intended.

Why would I sit there reverse engineering someone's code to write a document for them which codifies the bugs they didn't intend to make? They will just reject the doc "oh, thanks for writing this but that's not what's supposed to happen; that's a bug. Can you wait until next release and then change your document based on the new code? Thanks.".

Fuck that, you know?

Will the designer even take the document seriously going forward? Or will he just regard that as someone else's unimportant opinion about what a particular revision of his program did once upon a time?

We already know something about the designer's attitude is toward documentation, from the lack of it.

Satellite documentation: different story. I mean, tutorials, guides to internals and things like that. But, no, I'm not writing the basic, fundamental spec for your undocumented code you've already written.

> I am attempting to orient people into the "open-contribution" community, where we share the opinion that free software is NOT free to produce.

I agree with this position. I am also working on my own open-source projects, as well as other projects that I know have conscientious maintainers and a high-quality community. Why should I contribute my time to this project?

To be a little blunt: if this project has not thought about things like ownership of pointers and concurrency safety, it is not a project I think other people should use. My time is limited, and I use it on improving projects that I think are worth improving.

> for open-source software the developers couldn't care less (except maybe superficially, but this mental reward is insignificant for the long-term motivation for a project). They want to make a library that solves their own problems and is stable.

As an open-source maintainer, this doesn't describe me at all. I care more about things that improve the world than things that amuse me. (I also work on a few things that amuse me, but they're relatively clear about that status, and f they're not, I welcome someone calling me out on it.) All the long-term projects I work on are motivated by wanting that project to be a healthy project available as a compelling option for as many people as possible.

I had the rather delightful experience of starting a new job recently and finding that the next team over had just decided to start using a project I've been maintaining for a few years. If I had not spent time writing both code and documentation that welcomed unknown future users, this would never have happened. (And I still have not written nearly enough documentation for it!)

If my motivation were just filling my own needs, I probably wouldn't publish software at all. If it were that plus bolstering my personal brand, it would go on my blog or as CC-BY-NC-ND or something. My entire motivation for releasing software under a free license is for other people to use it.

>Does it take ownership of options, a struct with a single size_t.

This is a bit extreme. My first thoughts (honestly) is yes, what is the size of. Following their advice to follow their examples, I looked at examples and it literally just zeros a uiInitOptions on the stack and sends it in. Thus I think it's something I wouldn't really need to care about usually.

As for whether I need to worry about saving 8 bytes on the stack or elsewhere, that seems like such a rare question (amongst the questions people would have) that it would motivate digging a little bit. It took me probably 3 minutes to find the answer[0].

As someone said above, this is one cat's work in their free time. The gratuitous criticism is very unfair to them especially when you're worried about out circumstances most devs wouldn't have to deal with or care about.

[0] https://github.com/andlabs/libui/blob/master/unix/main.c#L11

"Usually?" What are the unusual circumstances? Will I need to care about it at an inconvenient time two years later?

I mean, yes, I can probably guess some things and end up with something that works with the current version of the library, but why would I choose this library to build on top of if I'm just guessing?

The code cannot possibly answer the question of what changes the developers may make to the project in releases they consider backwards-compatible. My question is entirely about the API, not about the code itself.

...not to mention that this is obviously a work in progress. We're looking at a project's github page, not a product release page. I would think that like with a lot of coding projects, you start with an initial idea and see where it takes you, rather than with a full specification that you then follow. Given the limited resources of a single programmer, writing an extended documentation early on and then keeping it maintained with every chance to the architecture would be a huge burden, time and effort-wise. That's not to say it cannot be done, but I understand if you want to spend your time on coding first, if it's a pet project. There's nothing that prevents documentation to be added in the future.

Yes, sorry—I should have been abundantly clear that I was responding only to the "You can figure it out yourself from the header file, you don't need docs" point. If it's an unfinished or hobby project, great! Those are cool, and I don't mean to discourage them / place high bars on them existing in public, and I am super sorry for not being clear about that.

Hobby or personal-interest projects with an expectation of no real use don't need externally-facing documentation because they have no externally-facing APIs at all, not because their APIs are obvious.

For my sibling comments: http://www.catb.org/esr/writings/unix-koans/prodigy.html

I see where you're coming from, but it's not a completed project if it's not documented. If it's only 1100 lines it shouldn't be hard to document it. If it's only 1100 lines and it's undocumented, it would probably be easier for me to continue using my own.

True. People seem to have expectations of open source projects now. They act like customers even if the programmer isn't a professional who is getting paid to work on it.

I work on several personal projects whenever I have free time and feel like programming. I keep them on private repositories because I don't think they are ready for publication. I'm not sure if they're ever gonna be ready.

With that many digits, uiPi should definitely have an L suffix.

Except that would make uiPi a long double, whereas every drawing API in libui just takes a double. Now as to whether the drawing APIs should use long double instead of double, I don't know; I will say that both cairo and Quartz/Core Graphics use double, so... (And on Windows, Direct2D takes floats, so at least on that platform, it's probably not going to make a difference at all...)

Reply on news.ycombinator.com