Vyatta's firewall distribution had some documentation which struck me as being remarkably well-written back in the day. Usage appeared to be well thought out. Don't know if their code is nice or whatever but if other aspects are any indication, I'd imagine it too is well done.
I'm only familiar with varnish 2.1, but as to that version I think it's a bit of a stretch to say varnish is well written. VCL is very complicated - just check the request flow diagram [1]. Some of the documentation is very poor - try to find out the properties available on beresp for example (you have to grep the source code [2]), or try to understand the precise function and implications of grace mode, saint mode, or hit_for_pass. The best redeeming quality is varnishtest and some of the other tools that are provided.
RxSwift https://github.com/ReactiveX/RxSwift is gorgeous. Cycle.js and RxJS also. Chromium + LLVM also (minus the x-platform parts but those suck everywhere).
Asterisk PBX. Well-chosen small set of module types (channel drivers, applications, functions, resources, codecs & formats), allowing to implement literally any behaviour, and converge with any thinkable external technology. Not working in VoIP anymore for quite long time, but the clarity of design of Asterisk has deeply influenced me.
Gstreamer. Pipeline is very powerful model for software, the potential of it is tremendous. Unfortunately I find level of development & maintenance of Gstreamer project itself quite poor - the code is horribly complicated for questionable reasons (it's said to be non-blocking everywhere; I find it bad excuse for being ridden with subtle bugs and for failures to use custom pipelines as blocks for higher-level pipelines).
I find such projects as ffmpeg and linux kernel quite well engineered, but have nothing special to say about them except that they are reasonably well organized and get better day by day.
For user-interface apps with considerations of high user productivity, I find such software as readline, tmux, mutt and bunch of other following wise pattern of extensible and scriptable software: if you want hotkeys, you need a domain-specific language and bindings must be
I am grateful to work with a few of the asterisk developers and they strive hard for quality. A project that long running and feature-rich is not easy to keep up to date, stable and well architected. If you want to see a project with professional commit messages, it is a solid example (the past several years at least).
Just in case anyone were to be led to believe this:
Asterisk's code base is a pile of crap.
It's been getting a bit better over the years, but it still is terrible, tons of conceptual blunder, protocol implementations are only losely inspired by the specification, system APIs are used incorrectly, lots of code doesn't bother with dynamic string lengths, but instead simply truncates strings arbitrarily if they don't fit into some fixed-size buffer, ...
The only reason it kindof works is because bugs that happen often enough do end up being fixed at some point, but that's about it. If you know your C and POSIX APIs and you don't believe me, just go and have a look at the code, I promise you'll find a bug in less than an hour.
Yes I know Asterisk is ridden with bugs and has very nasty spots at its core (e.g. "channel cloning" or whatever it is called). It was my job to debug the code with gdb and valgrind :)
What is still amazing to me is the set of core design concepts which I've listed - channels, applications... I have a case for comparison here, where the project is of comparable complexity but all features are bolted-on ad-hoc without such complexity compartmentalization which Asterisk has.
edit for details: The authors are quite meticulous (notoriously, every comment in a multi-line comment is 3 characters less than the previous) and stick to the "convention over configuration" mantra no doubt inspired by Ruby on Rails. It's interesting to see how they create abstractions to simplify so many common web dev tasks.
I've spent a lot of time reading C sources. Standouts are nginx, mbed TLS, Amazon s2n. Clean coding styles, consistent in checking function return values (very important! significant source of vulnerabilities in C software), comments where due, no hacks.
Among the most convoluted source codes I've read is Tor. It works (apparently), and it isn't even very insecure per se (the code is littered with hard asserts that will abort code execution if an expected condition isn't met), but it is unnecessarily dense. Example: I use software to analyze the call graph (which function calls which function) and when I ask it to find potentially recursive loops (A() calls B() calls A() etc) it spews out tens of thousands of potential recursions.
By comparison, mbed TLS only has a couple of these, and a large project like OpenSSL 50 or so.
Conversely, C software that isn't consistent in error signaling (return -1 on error in function A, return 0 in function B, set parameter int* err in function C, etc), doesn't perform due error checking, whose call graph is spaghetti, mindlessly performs multiplication (leading to overflows with certain inputs), uses signed or unsigned int where size_t is better suited, are usually susceptible to bugs and abuse (vulnerabilities). The projects I mentioned are very clean in this regard.
71 comments
[ 0.22 ms ] story [ 149 ms ] thread* Varnish Cache
* qmail
* Mercury Programming Language
[1] http://book.varnish-software.com/3.0/_images/request.png
[2] https://github.com/varnishcache/varnish-cache/blob/2.1/lib/l...
http://aosabook.org/en/index.html
[0] http://www.spinellis.gr/codereading/
Gstreamer. Pipeline is very powerful model for software, the potential of it is tremendous. Unfortunately I find level of development & maintenance of Gstreamer project itself quite poor - the code is horribly complicated for questionable reasons (it's said to be non-blocking everywhere; I find it bad excuse for being ridden with subtle bugs and for failures to use custom pipelines as blocks for higher-level pipelines).
I find such projects as ffmpeg and linux kernel quite well engineered, but have nothing special to say about them except that they are reasonably well organized and get better day by day.
For user-interface apps with considerations of high user productivity, I find such software as readline, tmux, mutt and bunch of other following wise pattern of extensible and scriptable software: if you want hotkeys, you need a domain-specific language and bindings must be
nothttps://github.com/asterisk/asterisk/commits/master
Asterisk's code base is a pile of crap.
It's been getting a bit better over the years, but it still is terrible, tons of conceptual blunder, protocol implementations are only losely inspired by the specification, system APIs are used incorrectly, lots of code doesn't bother with dynamic string lengths, but instead simply truncates strings arbitrarily if they don't fit into some fixed-size buffer, ...
The only reason it kindof works is because bugs that happen often enough do end up being fixed at some point, but that's about it. If you know your C and POSIX APIs and you don't believe me, just go and have a look at the code, I promise you'll find a bug in less than an hour.
What is still amazing to me is the set of core design concepts which I've listed - channels, applications... I have a case for comparison here, where the project is of comparable complexity but all features are bolted-on ad-hoc without such complexity compartmentalization which Asterisk has.
https://freeswitch.org/how-does-freeswitch-compare-to-asteri...
FreeSWITCH is an alternative to Asterisk.
http://imgur.com/a/E0idH
edit: https://www.chromium.org/developers/design-documents
https://github.com/erlang/otp
Especially the kernel in src/os
So far, it's the cleanest code I've ever worked with while still being very self-contained.
edit for details: The authors are quite meticulous (notoriously, every comment in a multi-line comment is 3 characters less than the previous) and stick to the "convention over configuration" mantra no doubt inspired by Ruby on Rails. It's interesting to see how they create abstractions to simplify so many common web dev tasks.
Among the most convoluted source codes I've read is Tor. It works (apparently), and it isn't even very insecure per se (the code is littered with hard asserts that will abort code execution if an expected condition isn't met), but it is unnecessarily dense. Example: I use software to analyze the call graph (which function calls which function) and when I ask it to find potentially recursive loops (A() calls B() calls A() etc) it spews out tens of thousands of potential recursions.
By comparison, mbed TLS only has a couple of these, and a large project like OpenSSL 50 or so.
Conversely, C software that isn't consistent in error signaling (return -1 on error in function A, return 0 in function B, set parameter int* err in function C, etc), doesn't perform due error checking, whose call graph is spaghetti, mindlessly performs multiplication (leading to overflows with certain inputs), uses signed or unsigned int where size_t is better suited, are usually susceptible to bugs and abuse (vulnerabilities). The projects I mentioned are very clean in this regard.
Underhanded perhaps?
Having an annotated guide for each software would be difficult but all of us have to start somewhere.