The 8086 Assembly source code of the MikeOS operating system is remarkably readable and easy to understand for such low-level software http://mikeos.sourceforge.net
Well, eye opening was the C++ source code I was able to work with at a previous company, they were an automotive HMI developer company. They had really strict and well planned code structure that just hit a chord with me.
Can't provide source though on that one, as it's a propietary engine.
Recently I've enjoyed reading the source code to Sokol, lot's of really good decisions there and I love the minimal C -style structure:
Nix doesn't use most of C++ features though. It's just the way project was organized and code was formatted that it looked beautiful and easy to skim through.
While at Grad school, before taking a course on Systems programming, I spent a few days reading through Redis source code. It felt almost like poetry.. I haven’t had that level of motivation or time to read open source code like that again.. so there may be better examples.. but this was my best…
PAIP is easily one of my favourite programming books. It’s chapter after chapter of excellently presented programming. Each chapter takes you through a problem, a solution (typically multiple iterations and extensions) with detailed explanations of what’s happening (often with historical details). Also, it introduced me to many different tools I can use to solve programming problems.
Nice example, note to do autocomplete with something neural based these days like https://text-generator.io or huggingface or spelling with neuspell etc
Peter did done great ground work here and as things transitioned to neural nets, also peter appears randomly in my Chromecast with some nice photos he took lol
One of the most surprisingly clear code bases is LLVM. It’s an old complex beast, yet it’s organized beautifully.
I mean, it has a lot of essential complexity but little accidental complexity.
That’s usually what I strive for when coding. Complexity is sometimes unavoidable, that’s fine, that’s why it’s essential. However, avoidable complexity should be… well… avoided.
I have not read it in a while but it would be interesting to debate what essays are no longer relevant. I'll be grabbing it off the shelf next to my original copy of the Byte issue on C mentioned yesterday and having a look for expired relevancy.
Reminds me of a book I picked up about twenty years ago called "Testing Computer Software". I think it must have been written in the 80s, because instead of having a bug database, it talked about filling out a hardcopy form describing the issue and dropping it off at the programming department. I reckon you'd want to do it in duplicate on carbon paper, just so you can keep it in your own filing cabinet.
wouldn't wikis be good the contemporary successors of that section? it's about documentation being disconnected from code, about co-evolving and providing both in an economical way, in contrast to being inefficient or even ineffective in documenting technology.
Rust is the only language out of those hyped that actually made me excited because it brings interesting features.
Additionally out of the box you have one cli with compiler, package management, etc. instead of 30 choices to pick from
C++ for me is just: terrible compilation times, 17 ways to achieve one goal, not strong ecosystem
Generally not the nicest developer experience in compare to e.g C# or apparently Rust.
I'd feel more motivated to jump into LLVM code base it that was written in Rust because I don't think C++ is the future - which is sad, because C++ has a lot of cool jobs now.
Seconding redis, and noting that the original redis source code is _also_ an interesting read and demonstrates how approachable well-written tcl is, even for those entirely unfamiliar with it as a language: https://gist.github.com/antirez/6ca04dd191bdb82aad9fb241013e...
I remember liking the java sdk java source. Great small focused functions and nice use of newlines. You could tell the developers were forged in an era without syntax highlighting and large horizontal screens. Extremely scannable.
The Java standard library will forever be my baseline for “good.” Perhaps the C# beats it, but then the overall ecosystem of third-party libraries is such that it isn’t worth the slight improvements in design.
For Angular, I think the “problem” lies in the level of abstraction. AngularJS was a “Spring / Java” answer to web applications with Angular following the paradigm but introducing reactivity to the system. Not “wrong” per-se, the quality of code is great and so I could recommend it at a tactical level of “good code” but at the strategic it feels off.
The problem with a reactive layout is that, if you're not going to just ask the user how they want to display things, you need to both read their mind and get it right 100% of the time.
Nobody can do that, so your web site shifts into mobile mode when I only give it half of my 3' display.
It feels like the logical end state of "clever" code, for better or for worse. Or, alternatively, what happens when a standard library is gigantic but each keyword is 1-2 characters.
I also came here to mention this video. Watching the solution emerge line-by-line is a profound experience, and highly revelatory towards the kind of iterative problem-solving workflow possible in the Iversonian languages.
In the same vein, John Scholes' collection of APL code in the Dfns workspace[0] is positively wonderful to read through. I think it's probably one of the finest repositories of annotated code ever assembled.
I quite like the FreeBSD src tree, as it comprises both the system kernel as well as the userland applications. The folders are organized similarly to the OS file system hierarchy, which I find helpful for navigating the source tree. I found it accessible to slowly learn how various parts of the OS work under the hood and compound my knowledge faster due to less context shifting, since it’s self-contained in one source tree.
Tangentially related, I found The Design and Implementation of the 4.4 BSD Operating System fascinating back in the day. I don't know how well it holds up now (or more importantly how relevant it is) but it was genuinely interesting, especially as I was using FreeBSD at the time.
Of course the one I wrote few months ago! When I re-read it today I realize how good I was at foreseeing all the problems that would eventually arise. The code has descriptive comments that explain not just what the code is doing but what it is supposed to do. I was very impressed with not just 100% line coverage but also complete branch coverage by rock solid unit tests. Sorry can't share the link because code is proprietary.
It’s not the best, far from it, but it was fascinating to me so I will share.
I used to work for a large newspaper. Engineering wasn’t the focus of the business, it was only a means to an end, it was just something they needed to have a competitive website. As a result, the churn rate was very high. But more interesting there was also a very high return rate. Engineers would come and go and return and leave again all the time.
As a result, the code base was a path work of various engineers with various skill level, different directions by different heads of engineering, repurposed old projects, legacy code and last minute additions by urgent request from the editors, among others.
The part I was most familiar with was what I can only describe as a sort of next.js but unlike it, it wasn’t planned or designed but rather it sort of grew organically over the years.
The fascinating thing to me was precisely this phenomenon. Some projects have a clear design and purpose and are built so from the start. Sort of like a building or a mechanical clock.
Others just evolve over time, they change, mutate, evolve, incorporate other bits. More like a biological organism or perhaps nature taking back a derelict settlement.
At first as you can imagine it was difficult to wrap my head around it. But in time, I started to see the beauty in it. It had historical bits. There was code written in 2010 that ran in 2020. Others you could tell little habits of the writer. Not everything gets stamped out by the linter. There was this guy who wrote “class ClassName extends React[“Component”]” - I have no idea why but I would run into code written by him and immediately recognise, ah yes, that’s that guy.
It’s certainly not an example of a good code base, but to me was interesting being able to see the code as a living organism with a history and fingerprints of it’s creators rather than a well designed machine.
The book "A Deepness in the Sky" features people living on an ship whose operating system is thousands of years old. One of the main characters is considered a software archaeologist of sorts - he's an engineer, but in a sense also a historical researcher.
I can't emphasize enough that this notion is only a side point in the story and not a main aspect of the plot, sadly, so I wouldn't go reading it in hopes of hearing more. (Although it is a great book regardless.)
I have often considered trying to write a scifi novel centered around this idea because I find it so fascinating.
The "software archeologist" idea has lived rent free in my head ever since I read the novel nearly twenty years ago. It's an absolutely fascinating premise, one I can most definitely see being viable to grow into a fully-fledged novel. I would definitely read that.
We're half-way there already. I've been telling people that the volume of software written has exploded exponentially, and the real skill anyone in IT has now is not knowing how to use a piece of software on a computer, but simply knowing that a piece of software exists to solve a problem.
These days I work largely in a cloud / devops role, and I can't even begin to list everything that I ought to be using but can't because there aren't enough hours in the day to keep up with all of the new developments. That's within a single language, a single web framework, and a single cloud provider!
I see projects where architecture astronauts stitch together multiple clouds, multiple languages, and some random junk on-prem that was installed over a decade ago by someone who has passed away since then. Within the expected lifetime of such a system, you'll need a software archaeologist to figure it out!
> I can't emphasize enough that this notion is only a side point in the story and not a main aspect of the plot
Is it sprinkled throughout the story, or a mostly uninterrupted block of text? As in: is there an easily findable chunk of the book one could read for that idea alone? If so and you could provide a few keywords or a direct quote, I’d be interested in grabbing the book to read that.
I just went and glanced over the text by searching a pdf for a few key terms - no, it's really just sprinkled. The idea doesn't get much attention and is mostly mentioned in passing.
There is the bit where the story of Pham’s youth is told. He was third son of a King on a medieval–tech world (one with ancient stories of flying machines and long–distance communication devices) when some traders from a distant world landed. To everyone’s surprise they were human, and had expected this world to have a much higher technology level when they arrived. Pham’s dad did some kind of deal where his son Pham was given to the traders as an apprentice; even Pham didn’t know the details. Pham spent the next 20 years or so living on the ship because he refused to use the suspended–animation system (too coffin–like). He learned use use the many layers of emulation to use older and older programs, and eventually learned even trivial details. For example, he learned that the epoch of the time system used by the traders wasn’t actually the date of the first moon landing, but was a couple of years after that. He even hypothesized that over the millennia, many ship’s captains would have installed back doors in the system that might now never be rediscovered (which turns out to be foreshadowing :).
One funny detail I remember is a throw–away line where someone rapidly keys in “a column of text”. If you’re paying attention you can combine that with names like Pham, Vinh, Nau, and Qung Ho, the rarity of the red–headed gene, and the descriptions of some traders from the far end of human space you can reconstruct how things went after Humanity reached the stars.
I regularly describe my day job (which consists in reading a 10-year old, arcane & barely readable Spring code base) as me working as a software archeologist. :)
People here on HN have compared the evolution of large and old code base to the evolution of DNA before and I think it makes perfect sense: E.g., in both cases, complexity has grown organically over the years/millennia and logic tends to be spread out over dozens of files/genes; change one line of code/gene and suddenly it will impact lots of other things; et cetera.
This is a natural development as the field matures. I've worked in codebases that had roots in the 1980s, and large chunks of code survived virtually unmodified from the 90s. I'm sure some here could tell stories of even older codebases.
Living codebases that have such old roots but have seen gradual maintenance and refactoring such that the whole thing didn't degenerate into spaghetti deserve a lot of respect in my opinion.
My old code was so tidy. Can't believe I wrote code like that. Although back then I think I mostly used vim. Not having any sort of IDE tooling does sort of tend to force you to be a lot clearer about what you do.
The last "take the time that you need, as long as it's bulletproof" job I had was in the late 90's. The concept of sprints introduced a drumbeat that precludes solid engineering, imho.
> Not having any sort of IDE tooling does sort of tend to force you to be a lot clearer about what you do.
True, but then I wouldn't be able to play whack-a-mole with pointer symbols during weird code-pairing exercises.
As my name implies - I’m half-serious in my sentiment. I’ve found many-to-most projects I’ve come across have personally-inconsistent conventions at a function level not to mention strategic architecture.
There is good code from other - but I feel many lack discipline in their initial approach and long term maintenance. In things as banal as variables. Not as a nit-pick but as a way of life.
Whenever I try to polish some piece of code into some immaculate crystal it only takes a short while before I go and make some change to it and then it looks like crap again.
I try to keep it at a level where it doesn't get too out of hand it can't be refactored in an afternoon, while at the same time refraining from masturbatory polish.
270 comments
[ 2.5 ms ] story [ 250 ms ] threadhttp://www.gtoal.com/sbt/
(see also the "Virtual Machines" book by Smith and Nair, ISBN-13 978-1558609105, if you are interested in this topic).
I can also recommend John Lions' "Commentary on the Sixth Edition Unix Operating System" - https://warsus.github.io/lions-/, Douglas Comer's Xinu (https://xinu.cs.purdue.edu) as well as Niklaus Wirth's "Compiler Construction" (https://people.inf.ethz.ch/wirth/CompilerConstruction/Compil...) and Project Oberon (http://www.projectoberon.com).
Can't provide source though on that one, as it's a propietary engine. Recently I've enjoyed reading the source code to Sokol, lot's of really good decisions there and I love the minimal C -style structure:
https://github.com/floooh/sokol
Peter did done great ground work here and as things transitioned to neural nets, also peter appears randomly in my Chromecast with some nice photos he took lol
I mean, it has a lot of essential complexity but little accidental complexity.
That’s usually what I strive for when coding. Complexity is sometimes unavoidable, that’s fine, that’s why it’s essential. However, avoidable complexity should be… well… avoided.
Nice one. I'll copy that.
http://worrydream.com/refs/Brooks-NoSilverBullet.pdf
Additionally out of the box you have one cli with compiler, package management, etc. instead of 30 choices to pick from
C++ for me is just: terrible compilation times, 17 ways to achieve one goal, not strong ecosystem
Generally not the nicest developer experience in compare to e.g C# or apparently Rust.
I'd feel more motivated to jump into LLVM code base it that was written in Rust because I don't think C++ is the future - which is sad, because C++ has a lot of cool jobs now.
I also remember how Qt UI code and docs were a revelation after the nightmare of win32 and related frameworks.
Bellard's original Tinycc was very entertaining and took a while to digest.
Most old and well-maintained projects are worth learning from.
Apart from some local tips and tricks what is more important is understanding that there's nothing special about other people's code.
An easier entry point might be the ethtool_ops in an earlier Intel network driver like e1000.
Node, by comparison, is a ghetto.
The problem with a reactive layout is that, if you're not going to just ask the user how they want to display things, you need to both read their mind and get it right 100% of the time.
Nobody can do that, so your web site shifts into mobile mode when I only give it half of my 3' display.
It feels like the logical end state of "clever" code, for better or for worse. Or, alternatively, what happens when a standard library is gigantic but each keyword is 1-2 characters.
In the same vein, John Scholes' collection of APL code in the Dfns workspace[0] is positively wonderful to read through. I think it's probably one of the finest repositories of annotated code ever assembled.
[0]: http://dfns.dyalog.com/
https://github.com/freebsd/freebsd-src
https://dl.acm.org/doi/10.5555/231070
I used to work for a large newspaper. Engineering wasn’t the focus of the business, it was only a means to an end, it was just something they needed to have a competitive website. As a result, the churn rate was very high. But more interesting there was also a very high return rate. Engineers would come and go and return and leave again all the time.
As a result, the code base was a path work of various engineers with various skill level, different directions by different heads of engineering, repurposed old projects, legacy code and last minute additions by urgent request from the editors, among others.
The part I was most familiar with was what I can only describe as a sort of next.js but unlike it, it wasn’t planned or designed but rather it sort of grew organically over the years.
The fascinating thing to me was precisely this phenomenon. Some projects have a clear design and purpose and are built so from the start. Sort of like a building or a mechanical clock.
Others just evolve over time, they change, mutate, evolve, incorporate other bits. More like a biological organism or perhaps nature taking back a derelict settlement.
At first as you can imagine it was difficult to wrap my head around it. But in time, I started to see the beauty in it. It had historical bits. There was code written in 2010 that ran in 2020. Others you could tell little habits of the writer. Not everything gets stamped out by the linter. There was this guy who wrote “class ClassName extends React[“Component”]” - I have no idea why but I would run into code written by him and immediately recognise, ah yes, that’s that guy.
It’s certainly not an example of a good code base, but to me was interesting being able to see the code as a living organism with a history and fingerprints of it’s creators rather than a well designed machine.
I can't emphasize enough that this notion is only a side point in the story and not a main aspect of the plot, sadly, so I wouldn't go reading it in hopes of hearing more. (Although it is a great book regardless.)
I have often considered trying to write a scifi novel centered around this idea because I find it so fascinating.
These days I work largely in a cloud / devops role, and I can't even begin to list everything that I ought to be using but can't because there aren't enough hours in the day to keep up with all of the new developments. That's within a single language, a single web framework, and a single cloud provider!
I see projects where architecture astronauts stitch together multiple clouds, multiple languages, and some random junk on-prem that was installed over a decade ago by someone who has passed away since then. Within the expected lifetime of such a system, you'll need a software archaeologist to figure it out!
https://www.drmaciver.com/category/programmer-at-large/ (down)
https://archiveofourown.org/works/9233966/chapters/20941043
Is it sprinkled throughout the story, or a mostly uninterrupted block of text? As in: is there an easily findable chunk of the book one could read for that idea alone? If so and you could provide a few keywords or a direct quote, I’d be interested in grabbing the book to read that.
One funny detail I remember is a throw–away line where someone rapidly keys in “a column of text”. If you’re paying attention you can combine that with names like Pham, Vinh, Nau, and Qung Ho, the rarity of the red–headed gene, and the descriptions of some traders from the far end of human space you can reconstruct how things went after Humanity reached the stars.
Living codebases that have such old roots but have seen gradual maintenance and refactoring such that the whole thing didn't degenerate into spaghetti deserve a lot of respect in my opinion.
I have a differing framework to an SPA, to an API, and to personal utility scripts. Amplified by adding in co-workers and contributors.
The Golden Question becomes how to communicate philosophy to a broad and diverse audience, be it co-workers or open-source.
C++ from 14 years ago:
https://github.com/vlofgren/tunguska/blob/master/tunguska_3c...
A career of Java development later, and the code I wrote yesterday looks like this:
https://git.marginalia.nu/marginalia/marginalia.nu/src/commi...
My old code was so tidy. Can't believe I wrote code like that. Although back then I think I mostly used vim. Not having any sort of IDE tooling does sort of tend to force you to be a lot clearer about what you do.
> Not having any sort of IDE tooling does sort of tend to force you to be a lot clearer about what you do.
True, but then I wouldn't be able to play whack-a-mole with pointer symbols during weird code-pairing exercises.
My code looks like a poem, others looks like chicken scratch.
There is good code from other - but I feel many lack discipline in their initial approach and long term maintenance. In things as banal as variables. Not as a nit-pick but as a way of life.
It seems… concerning.
Whenever I try to polish some piece of code into some immaculate crystal it only takes a short while before I go and make some change to it and then it looks like crap again.
I try to keep it at a level where it doesn't get too out of hand it can't be refactored in an afternoon, while at the same time refraining from masturbatory polish.