Documentation!

There is no doubt in this case I _am_ faulting the person who provided the code. Well, to be more accurate, I fault the project. The project should not accept the code without documentation.

Evidently you think this is unreasonable. But my attitude is actually worse, if that is possible - I hold different projects to different standards. I am perfectly happy with a buggy, poorly documented 1000 line utility I found on sourceforge. Yet when it comes to large projects like samba, apache and gcc I expect so much more. I actually expect code and documentation that is at least as good as I get from a commercial vendor. Can you believe that! I actually expect the open source process to produce a better quality product than something I pay money for!

Well unreasonable or not, I write the occasional open source program and I hold myself to those standards. You sort of have to really, because if you produce crap everyone can see it - you ain't some anonymous coder hiding behind an organisation.

Still, I don't produce code as good as I see in the kernel. Patrick, rusty and friends - they hold each other to the highest standards. New code that makes it into the kernel core is usually beautifully written. And the kernel project has a savage review process that ensures it stays that way.

Yet no matter how beautiful the code is, there is no point it if nobody uses it. And that is the situation netfilter finds itself in. Out of all the potential uses it might have it is deployed in, it is in but a fraction of them. This is because figuring out how to use it is a huge effort. Because there is no doco you have to read the source to get a true understanding of how it works. Thus only C programmers who are prepared to troll the kernel and iproute2 source really have a clue. Actually it is even worse than that. In the case of the schedulers the code is (necessarily) so complex the code only gets you part way there. You have to read the original academic papers on the algorithms used. (HTB, being the only scheduler written outside of the kernel team, is the one exception.) The situation is so bad its even defeated all the book writers.

So, returning to the original point, we have arguably the largest open source project of them all, the kernel, churning out code almost no one uses because they don't regard documentation as an important part of the final product. And yeah, I think this means the kernel development process is broken. And yes, I hold the people who drive that development process accountable. They could do so much better.