8 ms·

Code Is Not Literature (2014)

219 points by fanf2 3y ago

svat 3y ago
A great companion read to this piece, diving deeper into one of the anecdotes mentioned, is "Reading Programs with Donald Knuth" (2018) by Dylan Lederle-Ensign: http://www.dlederle.com/2018/11/25/reading-programs.html http://www.dlederle.com/2018/11/25/reading-programs.html Seibel mentions here that of his Coders at Work interviewees, only Knuth and bradfitz did a lot of reading of other people's code, and later his insight that Knuth's reading style was not passive, and more like a "scientific investigation". This post goes into more detail about a concrete example of "reading", very similar to the one in the post (about the Fortran compiler for Bunker Ramo 300, that he read without knowing the operation codes): this one is about a program where again Knuth reconstructs "a listing of Whirlwind opcodes based on the program listing". I think seeing the actual details of what "reading" code entails—the specific margin notes etc–is very illuminating. It is also probably no coincidence that Knuth came up with literate programming (not only is he a writer at heart, he was a seasoned reader of other people's code, that too machine code!), and also somewhat addresses the complaints about Knuth's own examples of literate programming seeming unreadable: his threshold for what counts as "readable code" is different; code is not expected to be read like reading a novel but more like (his way of) reading a technical paper.
ozim 3y ago
Bad part is - as a young dev I was into Knuth and Uncle Bob and formatting code in beautiful way so someone who reads it is not amazed but gets the ideas what and why instantly. Worse for me was realization that we don’t speak the same language with people and making ‘a + b*c’ does not mean really much for people and they rather nag that I am not using spacing uniformly. So I declared bankruptcy on intelligent code writing and became brute as others so I don’t even care how variables are named I will just debug it 5 times or more with different inputs and I will know for sure what the code does. Keep in mind Knuth and Bob Martin come from old school where you had to wait long for getting your code run - nowadays I can run locally code multiple times and find out what it is doing on the spot … so my point code or beautiful code means a lot leas in daily work than 40 years ago…
Sparkyte 3y ago
Eh I would propose it is. Just not literature for everyone. You wouldn't go around saying something written in Japanese is not literature because it is a different language and follows different rules to read it. Same applies to a programming language, you need to be able to know how to read it to know what it is doing. You don't need inline comments, unless there isn't enough clarity in the code itself and someone shouldn't bend over backwards to sacrifice performance over readibility.
elihu 3y ago
I think most code doesn't really stand on its own very well. In order to understand it, you need to know a number of other things that might not be obvious (especially if the code in question has bugs, or has been rewritten a number of times and has some historical relics from earlier designs that are no longer relevant): What is this code supposed to do? What is the general execution model? What are the rules the implementation must follow in order to maintain correctness? The way code is written, it starts first as a collection of ideas, and then it takes concrete form as code. Reconstructing the ideas from the code may be possible, but sometimes it requires some extra help. Some things are best explained in English (or some other preferred native language) as ordinary written text. Some things are best explained as state transition diagrams. And some things can be expressed most clearly and concisely as code.
code_thr 3y ago
Code is literature. It's just that most of us are writing the equivalent of the Complaint tablet to Ea-nāṣir rather than Gilgamesh.
pflanze 3y ago
Previous discussions: 240 points|10 years ago|83 comments https://news.ycombinator.com/item?id=7091495 https://news.ycombinator.com/item?id=7091495 112 points|6 years ago|65 comments https://news.ycombinator.com/item?id=13855185 https://news.ycombinator.com/item?id=13855185 66 points|4 years ago|13 comments https://news.ycombinator.com/item?id=20667467 https://news.ycombinator.com/item?id=20667467
phibz 3y ago
I tend to treat code more like poetry or music. Its a shorthand for instructions telling the computer what to do. Depending on the language, naming, structure, and comments the original thesis may be lost or hard do understand. And in isolation short snipets don't often mean much or can change their meaning without context.
naruhodo 3y ago
After years of doing software maintenance of other people's code, my doc-comments have grown longer and longer. Software maintenance is often the kind of reverse-engineering challenge that Knuth describes in the linked article. I hate ambiguities and mysteries in code. I make it my mission to provide a complete mental snapshot of the domain knowledge required to understand anything I write. My doxygen doc-comments of C++ namespaces and classes have grown to the length of short blog posts containing a comprehensive introduction and overview to the topic, replete with links to external references. Some programmers probably hate me for this. Maybe a few love me.
kitanata 3y ago
[flagged]
meltyness 3y ago
There's legitimate tension here. With FOSS, the common desire is to build fix or modify, but frequently non-code explanations are sparse. That's one place where code reading is certainly desirable, and obviously the reverse engineering described.
parentheses 3y ago
Name code every programmer has probably read? My answer: Carmack's fast inverse sqrt
sinuhe69 3y ago
When it comes to reading code, the real question isn't just why—it's about when we do it, what we read, and how we go about it. As programmers, we all know that reading code is valuable, and we often tell ourselves we should do more of it. But let's be real, life happens and we don't always get around to it. One big reason? Time—or the lack of it. Unlike writers who can afford to read day in and day out, our job is to write code. So, when do we actually read code? Usually, when we need to. It might be diving into an API's documentation or snagging a code snippet from Stack Overflow to fix something. But here's the catch: once we figure it out, we tend to forget it. That's why if you asked me what code I read last week, I'd probably draw a blank. Sure, we do some reading here and there, but I think we should step up our game. When we solve a problem, we pat ourselves on the back and move on. It worked, right? But here's the thing: we can learn a lot by peeking at how the experts do it. Think of it like reading a book. We don't just skim the words; we dive into the plot, dissect the characters, and think about what makes it tick. Learning from others' code isn't all that different. When I started learning F#, I was blown away by the variety of solutions out there, all doing the same thing in completely different ways. Comparing them with my own attempts taught me a ton. Bottom line, we should always keep that student mindset. Don't just glance at code—study it. Pick it apart, understand its structure, and figure out why it's built the way it is. Whether you're a seasoned pro or just starting out, approaching code with fresh eyes can unlock a world of ideas. So, let's make time for it, even if it's just a little bit. It's an investment in our growth, our skills, and our identity as programmers.
kunalgupta 3y ago
i should never have smoked that shit now i can’t stop seeing everything manmade around me as literature
silviot 3y ago
Oh, this is by the author of "Coders at Work". I can recommend that: a good read!
- messe 3y ago
  And Practical Common Lisp, another popular one on HN. The domain name took me by surprised and I struggled to remember why it seemed so familiar; it turns out that PCL can be found in its entirety here, and I had used it years ago to learn CL: https://gigamonkeys.com/book https://gigamonkeys.com/book
imachine1980_ 3y ago
(2014), my lord
gwbas1c 3y ago
> The biggest lesson so far is that code is very dense. A half hour presentation is just enough time to present maybe a dozen meaty lines of code and one main idea. It is also almost certainly the case that the presenters, who have to actually really dig down into a piece of code, get more out of it than anybody. But it does seem that a good presentation can at least expose people to the main ideas and maybe give them a head start if they do decide to read the code themselves. Which exposes the disconnect: A computer program is not about expressing an idea; it's about doing a thing. It's a very specific set of instructions that explain how to do a thing; often having to handle corner cases that a human would not need explained to them.
- ilrwbwrkhv 3y ago
  100%. A lot of new programmers who didn't program back in the day have been used to this idea with abstractions and "clean code" and that causes so much issues these days. Instead the mental model should be how does the computer achieve the thing that I am trying and how can I make that happen with the fewest lines of instructions as possible. A computer program is an instruction set as you rightly said. It is not a long winded story with many "nouns" (objects).
  - mochaki 3y ago
    [dead]
  - pixl97 3y ago
    >t I am trying and how can I make that happen with the fewest lines of instructions as possible Isn't that the compilers job?
    - gwbas1c 3y ago
      The compiler doesn't know how to reduce three database round trips into one database round trip. Modern compilers are awesome, but they still can't read your mind to understand your intent and suggest changes that would objectively change the program, but do what your intent is in a much better way. Perhaps someday artificial intelligence could, but I think that is a long ways off.
wduquette 3y ago
> As I prepared my presentation, I found myself falling into my usual pattern when trying to really understand a piece of code—in order to grok it I have to essentially rewrite it. I’ll start by renaming a few things so they make more sense to me and then I’ll move things around to suit my ideas about how to organize code. Pretty soon I’ll have gotten deep into the abstractions (or lack thereof) of the code and will start making bigger changes to the structure of the code. Once I’ve completely rewritten the thing I usually understand it pretty well and can even go back to the original and understand it too. I have always felt kind of bad about this approach to code reading but it's the only thing that's ever worked for me. This has also been my experience over the last thirty-odd years, whenever I have to take over maintenance of someone else's code.
- csours 3y ago
  There's probably a better way to say this, but here goes: Anything you learn before you start working on something is familiarization. Familiarization is important, but it is not working knowledge or understanding.
retrac 3y ago
The right analogy is not to literature, but schematics of the architectural or mechanical kind. Those can also be beautiful, works of art, and objects of study. Sometimes a clever blueprint will allow seeing some aspect of construction that isn't otherwise obvious. But the prints are not usually the centerpiece for a discussion in their own right. The object depicted - a building or whatever - is the main focus. Going back to the literature analogy, reading groups are for fun (usually). Spark ideas and discussion. Code is too low level. It's like discussing the author's grammar and word choice -- sometimes necessary to understand the meaning of the text! - but most would prefer to discuss high level themes in the work.
- agentultra 3y ago
  Even then I would say code is not the blueprint but an artifact. Specifications of the precise, formal variety are more akin to blueprints [0]. They allow us to see the design of a system at a high level while eliding unnecessary details. Source code for programs are limited in that they can only express ideas about their local state. Barring high-level languages with dependent-type systems it is nearly impossible to model and check that your transaction consensus protocol works as intended without getting into a ton of gory detail... much more so if you want to check global properties of the concurrent system you're designing. I think Sussman was right: we often start with a pure model of what we intend to design but the artifact we produce, the source code of the actual program, is usually full of details that only matter to get the program to produce the expected behaviour when executed... and all that extra detail tends to drown out the core ideas. [0] https://cacm.acm.org/magazines/2015/4/184705-who-builds-a-house-without-drawing-blueprints/abstract https://cacm.acm.org/magazines/2015/4/184705-who-builds-a-ho...
  - jll29 3y ago
    Along these lines, the perfect programming language would be one that eliminates all boilerplate that can be eliminated, one that leaves behind "pure design". "The result of the execution of the blueprint is the building."
- temac 3y ago
lincon127 3y ago
[flagged]
- Koshkin 3y ago
  I think 50% of my coding knowledge came from reading other people's code.
  - lincon127 3y ago
    [flagged]
falcolas 3y ago
The main argument appears to be that code is best dissected and understood, whereas literature is not? There's a fair number of philosophical texts which would disagree. Even "simple" engineering/physics/mathematics/science books often require a deep understanding, even though they're describing something, not providing directions. It's also often important to understand the context in which a piece of literature was written, just as it is important to understand libraries and the runtime context. In other words, I think it's fine to think of code as literature, just perhaps not the same literature the author frequently reads.
- Sparkyte 3y ago
  you decompose literature by dissecting it so the article is moot I agree
- Supermancho 3y ago
  > The main argument appears to be that code is best dissected and understood, whereas literature is not? There is no reference to "best". The issue is why codebases are not read as often as developer culture has doggedly engrained that it should be. A codebase is not enjoyable as a narrative or mechanically instructive, as you have implied due to the large number of confounding factors and approaches available. Literature is primarily a form of communication, while code is primarily a means to perform. It does not fit as "useful" literature. Most of the time, reading a codebase is like reading a manual that's faded and torn and was 500 pages long (now 486). You might learn something, (fast inverse sqrt and such) but this is as incidentally useful as a pithy wisdom buried on page 322 of a VCR Manual. Nothing about why they wanted to specify 2 buttons in tandem to eject the cassette^ or why it has cooling off instructions^^. ^ The build system/factory was making a similar device that required 2 buttons so management saved some money. ^^ The rewinding mechanism tends to heat and kill the whole device for a time. The original rewinder didn't fit the case 4 weeks from production, so a primitive replacement from a vendor was used which has this problem.
taeric 3y ago
Interesting to consider this in the light of how Knuth intends literate programming. Specifically, his version of "literate" is specifically dissecting the code for presentation. Sometimes you show broad strokes of the overall structure of the program you are presenting, but most of the time you dive into the details. It is funny as most of the time the big complaint is that there is still code there. It is not uncommon for the code to start with a section showing a basic C file with some standard includes at the top. And those will sometimes just have a shorthand C comment embedded in them for why they are there. This seems to frustrate many that think the entire thing has to read like a novel, but it makes perfect sense in the "dissected program" presentation of the code. There was a fun video I saw once of Knuth "critiquing" the code of his class. He called out liking the way first person was defined for use in the prose section and would spend time talking about the different stylistic choices of things. I'll have to try and find that again.
- RaoulP 3y ago
  Please do, I would be interested.
  - taeric 3y ago
    I found https://www.youtube.com/playlist?list=PL94E35692EB9D36F3 https://www.youtube.com/playlist?list=PL94E35692EB9D36F3, which is a giant list of all lectures. I can't remember the specific one I was thinking of. There are a few there that are titled writing and literate programming. I'm guessing it is one of those, but I don't have time right now to watch them and confirm.
    - RaoulP 3y ago
      No problem, thanks!
gavinhoward 3y ago
I am one of the programmers that like to make dissectable code. In fact, I've included a whole manual, with my most famous project, that is entirely about dissecting the code. [1] And I will certainly do the same in my current project. Some of the most delightful moments I've had are when someone emails me with questions that indicate they've read my code, such as mentioning specific comments or asking about something in that dissection manual. I consider it a badge of honor if people think my code is good enough to study. [1]: https://git.gavinhoward.com/gavin/bc/src/commit/75cf2e3358b5/manuals/development.md https://git.gavinhoward.com/gavin/bc/src/commit/75cf2e3358b5...
- alexvoda 3y ago
  Just had a look. That is a wonderful intro document for your code base.
  - gavinhoward 3y ago
    Thank you very much!
- Pr0ject217 3y ago
  Inspiring
- hinkley 3y ago
  I think if we sat over beers we’d find some common ground. I sometimes like to think of good code as short stories. Badly factored code is like a novelization of a story. Too long with too many side quests and you only find out at the end that the butler didn’t do it. Whether that pleases or infuriates is a gamble. Excessively terse code that requires broad life experiences to unpack? It’s interpreted by every observer to mean something different. Like a haiku, or even a song, the story being told is unclear. Beautiful, moving, but unclear. I much prefer short stories. A little flavor text, but no time for more than two clever ideas at once.
  - ljm 3y ago
    when you think you have a good story to tell you will make it work no matter what. Epic poems like The Iliad or Baghavad Ghita or the bible are not immaculately retold from scratch but depend heavily on repetition and context cues. Code is the same.
WillAdams 3y ago
I believe: http://literateprogramming.com/ http://literateprogramming.com/ and the publication of: https://www.goodreads.com/book/show/499934.Computers_Typesetting_Volume_B https://www.goodreads.com/book/show/499934.Computers_Typeset... https://www.goodreads.com/book/show/1746886.Computers_Typesetting_Volume_D https://www.goodreads.com/book/show/1746886.Computers_Typese... https://www.goodreads.com/book/show/8981752-physically-based-rendering https://www.goodreads.com/book/show/8981752-physically-based... would argue against this. Esp. see: https://www.goodreads.com/book/show/112245.Literate_Programming_Volume_27_ https://www.goodreads.com/book/show/112245.Literate_Programm...
- toby- 3y ago
  The article does mention Knuth, the author of three of the books you mention.
  - WillAdams 3y ago
    I think it would be more accurate to say the "most code is not literature" since it is not documented in a fashion which makes it readable --- and it would be more interesting if the examination/re-writing of the code was done in a literate fashion. The largest project I ever did (typesetting back-end for an on-line interactive ad design system) was done as a literate program, and over the course of years of maintenance was far easier to work with than other smaller code bases which I hadn't taken the effort to so structure and document. Arguably, I need to re-work my present project thus: https://willadams.gitbook.io/design-into-3d/ https://willadams.gitbook.io/design-into-3d/
thenoblesunfish 3y ago
I realized something perhaps similar which is that math is not literature. The only way to really learn anything is to go back and forth between reading and doing. Reading through a giant piece of code feels a bit like reading a math book and not doing the exercises. You'll get some good ideas and overview, but you won't really get "it".
eterevsky 3y ago
This is a bit weird to me since I never thought someone would just go and read source code of some program from start to finish. It would be something like reading an encyclopedia starting from the letter A. That said, I personally DO read code. Besides code reviews that were mentioned in the article I read the code that my code depend on. Especially when I want to better understand some API, I read not only the headers, but the actual implementations of the functions that I'm using. Sometimes I read code to better understand some algorithm. I only understood how Transformer architecture worked when I read some of its implementations. So yeah, reading code is cool. We just don't read it as we read books.
- LeanderK 3y ago
  yeah, weird. I read a lot of code. I often read code to exactly understand what's going on, how specific functions are used or how the API was intended to fit together. That may mean that I read random code on github, code of my dependencies etc. But it's not a continuous reading of code. I don't read the code of my dependency from start to finish.
- Joker_vD 3y ago
  > someone would just go and read source code of some program from start to finish. Well, one has to start reading from somewhere, and the start seems like a good way to start, is it not? Well, actually, no, it's not, because you have to waddle from main through like ten levels of procedure calls until some actual work starts being performed, but if you don't know where exactly the interesting parts are the only other options are either try to grep (doesn't work reliably in repositories where the authors like short and cryptic names) or to read source files until you find the relevant place. > It would be something like reading an encyclopedia starting from the letter A. I actually did something similar as a child, except I'd just open it on a random page and start reading. There is nothing really wrong with that as a recreational reading IMHO.
  - kaba0 3y ago
    I remember there was a blog post saying that everyone should write an ARCHITECTURE.md file as well for their projects. It’s content can be a great starting point(s).
dimal 3y ago
I still think it's literature, just that most of it is trash literature. But then again, I was an English major and was trained on how to dissect literature. I realized a while ago that there was a book and a method I learned in English Lit 101 that I think informed how I read code. It's called The Critic's Hornbook, by William Dowling [0]. In short, it's a methodology for meticulously breaking down the meaning of every word, phrase and reference in a text, without resorting to any subjective interpretation. He showed us how, with proper understanding and research, you can find a lot of latent information about what's going on in the text. I find myself doing something similar when I read code, and when I write code. Code reading is also archeology. There are always layers of code accumulated over time, and you can start to see the minds of the people from years ago. And if you understand the constraints they were under and the assumptions they had, then it can help to understand "Why the hell did they do it _this_ way?" [0] https://www.amazon.com/critics-hornbook-Reading-interpretation/dp/0690008848 https://www.amazon.com/critics-hornbook-Reading-interpretati...
- wglb 3y ago
  Sounds like you are invoking Sturgeon's rule.
  - dimal 3y ago
    I suppose I am. I think I’ve so fully internalized that idea that I forgot it’s not my idea!
- foundart 3y ago
  > it's a methodology for meticulously breaking down the meaning of every word, phrase and reference in a text, without resorting to any subjective interpretation How many words have only one meaning? In the presence of words with multiple meanings, how does one non-subjectively choose the meaning to apply to a particular usage when dissecting a particular work? I'd love to hear more.
  - dimal 3y ago
    It’s been a long time since I did it at school, so I think what I do with code is more “informed by” that process than a duplication of it. But one specific thing I remember was that you look at context. One example I remember from school was reading The Love Song of J. Alfred Prufrock, and how by describing the fog as yellow and a few other details, we could infer that the setting was almost surely London, although that’s not stated. Another fun thing was reading old literature at looking up word after word in the OED to understand what a given word meant at the time that the text was written. This was a mind-blower. All these sentences that seemed very pretty but kind of confusing suddenly became very clear when you interpolate the older meaning. And then every clue you get builds up more context that you can use to infer other aspects about setting, character, etc. So, I think there is a fair amount of inference, but it should always be logically and objectively grounded.
lifefeed 3y ago
I like to distinguish between Programming and Software Development, even though I don't have precise definitions for them. Programming is what you find in code samples and books and tutorials, where the code is clean is readable, and is what most of us fall in love with. Software Development is all about diverse and messy and malicious inputs and outputs, and the code is filled with the hairy edge cases[0], and it is not fun to read, but it is what most of us get paid for. 0 - e.g. the classic https://www.joelonsoftware.com/2000/04/06/things-you-should-never-do-part-i/ https://www.joelonsoftware.com/2000/04/06/things-you-should-...
aatd86 3y ago
Is a cookbook literature?
- Supermancho 3y ago
  I would say so (not the same as a recipe). In this way a recipe and the ten commandments look the same. Reductionist comparisons are pretty easy to make. Sometimes code and recipes look the same, if the codebase is small enough and both omit the deployment/build chain/tooling in favor of implied requirements.
  - aatd86 3y ago
    What's the difference between what is literature and what is not literature then? I realize I was taking for granted what literature was? (I have an idea but I will add it later)
    - Supermancho 3y ago
      As far as I can tell, literature is a form of explicit communication to the naive reader, which intrinsically provides context to interpret it. The README is literature. The code is not (common case). A cipher is not literature, even if that cipher is breakable, resulting in literature. It may be useful to consider it literature if you know the cipher, but it is not until that transformation has occurred. You may recognize this if you try to read a story written by a child or mentally disturbed individual. The story might skip or be interrupted/incomplete or is otherwise nonsensically mangled structurally and narratively. Literature implies literacy to access the medium both ways (reader and author). Broken manuscripts are not literature, per se. Literature is a soft term, so what I think holds no value other than how it might well describe the populist zeitgeist surrounding the term.
      - aatd86 3y ago
        So literature is a communication form while code is information (i.e. What's being communicated)? Makes sense.
tabtab 3y ago
2B || !2B
the-printer 3y ago
> Seibel: I’m thinking of the preface to SICP, where it says, “programs must be written for people to read and only incidentally for machines to execute.” I’m wondering if the initial statement in SICP spoke from a time that was similar to a 1977 McGraw-Hill textbook, “Introduction to Computers”, that I picked up from a thrift store recently. A significant portion chapter on developing computer programs is dedicated to methodology; planning, the development life cycle, systems design, instructing users, processing methodology. The next chapter is about flowcharts and tables. I mention all this to point out how intrigued I am by what looks like the emphasis that was placed back then on clarity from the human’s perspective, be it programmer, user or anyone else involved in the software’s development and use. Another thing that’s interesting to me is how old code like Fortran looks like it’s made up of mostly just words, compared to modern languages I’ve looked at that use a lot of abbreviations and special characters. My knowledge of programming and its history is excruciatingly minimal, but this blog post and that excerpt sort of remind me of what I just mentioned. I’m not sure why exactly, or if there’s any credence to it.
- wduquette 3y ago
  I've spent a lot of time trying to make sure my code is commented and easily readable; and I haven't found any of that time to be wasted. I've often had to go look at code that I wrote two years, or five years, or twenty+ years previously, and I've greatly appreciated the work I put in when I wrote it.
- SoftTalker 3y ago
  The approach in 1977 was that the problems we address with computer programs were static. It was up to the system developers to understand the problems well enough to learn their requirements and then implement the requirements as code. Writing the code was the last thing you did, after the problem was entirely understood, documented, flowcharted, signed off by the client, etc. Now we understand that the problems often change as the code is developed, or in response to the code we develop. Priorities and requirements change as the work proceeds. We start writing code early, solving small parts of the problem, and building up a solution almost organically, the way a tree will grow around obstacles in its pursuit of sunlight. The name Fortran is a contraction of "Formula Translation" it was developed to be usable by mathematicians and scientists. COBOL is another language that looks very wordy, as it was developed to be used by businesspeople.
gilessbrown 3y ago
Code isn't really literature. It's more like a contract. It needs to be intelligible and clear because it will be taken more literally us humans can generally imagine.
beardog 3y ago
I argue that (good) literate programming can make code literature. Your program is told as a sort of story and ought to contain background info, thought processes, and rationale for decisions. Additionally macros can be used to reuse code at build ('tangle') time that your underlying language may not otherwise support. For example if I have some constants i need throughout a python program, I might put it in something like constant.py during normal programming, but if I were literate programming I could have a section called "Program constants" and dive into each one, referencing them with macros throughout the program. You do have to be careful because the macros can make debugging confusing since you are now working with two languages instead of 1. You can also put stuff that is irrelevant to humans out of the way of the most important stuff. Example literate program for writing a virtual machine program (not my work): https://www.jmeiners.com/lc3-vm/ https://www.jmeiners.com/lc3-vm/
pxc 3y ago
I read code for fun sometimes, but it's usually not whole codebases. I like to read PRs that I think are exciting in projects that I use, and then branch out to the context that they're invoking or changing as well. I've never thought of it as something I do to advance myself as a programmer, though. I just kinda do it on impulse, and I'd still do it even if I found out it didn't really improve my skills. Anyone else recreationally browse PRs in F/OSS that they use, kinda like reading the news?
atomicnature 3y ago
It is a new kind of literature, with the key characteristic being "dynamically sequenced reading". Unlike literature, code is supposed to be read in an order most conducive to the reader's goals, rather than the author's goals. Also, unlike literature, often new code is built upon old in an explicit and direct way. Although even in literature, one builds on top of old ideas. I think Peter Norvig once commented on why Knuth's Literate programming didn't catch on. His guess was that, people usually have a specific purpose when they are looking into a piece of programming, and they want to read it in an order most suitable to them. With LLMs, there could be dynamic code exploration helpers, I think. They could take our goals, and then introduce parts of the code that are relevant to the reader, with extended guidance...
bregma 3y ago
The premise is wrong. Well, it's not wrong, its just that it's premised on the definition of 'literature' being 'high brow writing for the elite' in the sense of something that can be dissected and analyzed for the sole purpose of revealing something about the human condition. It's true that computer program code is not that kind of literature and no fine arts major is likely to ever write a graduate-level thesis on it expounding the symbolic allusions to the Christian Bible and how it represents society's fear of death and desire for sex. Source code is, however, literature in the sense that it is written for people to read. Not for computers to read. People. Sometimes other people, often the original author at a later date, but people nevertheless. By definition, that makes it literature.
- lifeisstillgood 3y ago
  completely agree. Even writing a book on "software literacy". A small side note - most of us will know a manager who "used to code but stopped when went into management". But none of us know anyone who stopped reading and writing English (German, Japanese) when they went into management. The difference might be that we don't have many companies that can be managed with code, or that a lot of people in management don't need to be there. Edit: VW is an interesting case in point. It does not matter what a manager says, what the design document lays out. what matters is what the code says. And VW CTO knew this so he made the commits to the code base that tricked the emissions tests. That is management-by-code.
- deleted 3y ago
  [deleted]
egonschiele 3y ago
I'll present a different take. There are some basic things you can do to make your code more readable: - avoid double negations - use grep-pable names and avoid string interpolation - keep code duplication if that version is more readable and maintainable. I'd love to see a longer list. In my experience, engineers too often code as if keeping the code as short as possible is what matters, instead of optimizing for code that is easy to read.
javier_e06 3y ago
The headline makes me reminisce of a object oriented class I had years ago. The instructor asked: "If you are coding a black jack game, who shuffles the deck?" The dealer we all responded. "I daresay that the deck shuffles itself" the instructor replied. In Literature that is impossible. Unless you are reading Alice In Wonderland.
creer 3y ago
Code is rarely meant to be read. Even when we have to read the code to sort out some problem, or to reuse the principle at the core of it, reading is hard enough. One eggregious example that comes to mind was code released with all comments stripped out and largely obscure variable names.
InitEnabler 3y ago
For me code may have elements of syntax like literary language, its primary function is to convey logical instructions and operations. imho.
hnfong 3y ago
I think the comparison is a bit "unfair". When writing was first invented, it was presumably, mostly for functional purposes. Keeping records; Calculating taxes; Government administration; etc. If one looked at writing at early stages of development, one could very well come to a similar conclusion that "Writing is not literature". And that still is true, mostly. Writing generally is not literature. Just look at the comments under a Donald Trump video for example. Not sure anyone would want to read those. In fact I'm pretty sure <0.1% of the comments here in HN would qualify as "literature". But if you said "Writing is not literature", despite it being true, it's probably misleading. The term "literature" is generally reserved to the finer styles of writing that in addition to whatever functional purpose it served, had an aesthetic to it that makes it worthwhile for others to read. Most literature comes from a long tradition where styles and techniques are developed to make the text more interesting and pleasing. The traditions and the corpus of literature grow stronger as time goes by. Of course, best works accumulate and are archived for future generations to study as well. This has gone on for thousands of years for "natural language literature". It has a head start of thousands of years. Code has been invented for less than 100 years. That's nothing in the greater historical context. Imagine digging up ancient clay tablets of which 99% talk about how much bales of barley we need to collect to feed workers next year, and concluding that this language/culture is not capable of literature. That's what the article is arguing essentially. But do we have evidence otherwise? Are there code so aesthetically pleasing (or at least interesting) that it might be read just for pure joy? Yes there is. Just not a lot. For example, check out the entries of IOCCC. Some of them are insanely beautiful, and I have no idea how the authors could have created them. They're the equivalent of carefully written poems in C, except they're possibly even harder to write. So yes, while I agree that the article is probably literally correct in saying (vast majority of) code is not literature, I think it's wrong to interpret that statement as "code can't be literature". It obviously can be in a substantial way. It's just that the cultural norms haven't caught up yet, and while people today somehow think they become more "refined" after reading for example Shakespeare (which I have no idea why besides gatekeeping attempts from the elite class), the programmer class hasn't yet taken over schools to shove quick reverse sqrt (0x5f3759df - ( i >> 1 )) down student's throats and call it a well-rounded education. (Tangent: yes, all the things you felt were useless in school are probably really as useless as understanding Q_rsqrt, i.e. not very useful unless you really need it, but 99% people don't really except for showing class status) I grant you that I can't think of any equivalent to long form novels that might work in code, since telling and listen to stories are somehow baked into basic human psyche for which code has no equivalent, but literature is more than novels so I'd claim at least code can be a meaningful subset of literature.
vaughan 3y ago
Code should be more like a children's popup book with little tabs to pull on to make things move around. When I look at a foreign piece of code I want to see all the runtime values inline in my editor and a time-travel debug session with a slider and a stack trace of the function under my cursor, and a trace of the _value_ under my cursor showing every transform that happened to it, and all common data structures and their algorithms visualized and animated in appropriate diagrams. And available in all our tools instantly - like when viewing code on Github.com. I really think you could figure out what is going on with most code if you simply move a slider back and forth and watch everything that changes. And it would be much more fun with a physical knob to turn (e.g. https://www.tourboxtech.com/ https://www.tourboxtech.com/ or https://www.binepad.com/product-page/bnr1-v2 https://www.binepad.com/product-page/bnr1-v2). Knob-driven development :D
- darkmarmot 3y ago
  Have you tried doing this with distributed computing? It's not very feasible...
  - vaughan 3y ago
    Local simulation + deterministic record-replay.
- scottlamb 3y ago
  Heh. I think you have the absolute opposite viewpoint from Rob Pike, who said of syntax highlighting [1]: > When I was a child, I used to speak like a child, think like a child, reason like a child; when I became a man, I did away with childish things. I'm with you! That sounds awesome. I enjoy not only syntax highlighting but also type annotations and doc references on hover. I'd love to see even richer and more interactive stuff. [1] https://groups.google.com/g/golang-nuts/c/hJHCAaiL0so/m/E2mQ1RDiio8J https://groups.google.com/g/golang-nuts/c/hJHCAaiL0so/m/E2mQ...
m1n1 3y ago
One thing I've done in the past is put comment "tours" in the code so you can follow with your IDE's search. Each comment has the name of the specific tour, a number, and the tour guide's blurb. This lets the visitor follow a nice sequence, across different files if necessary... Sort of like the inverse of literate programming
- ravenstine 3y ago
  I'm all for using comments, but you have to be on a team that's on board with them. I've joined more than one team that adopted the "the code should be its own documentation bruh" attitude, as if comments get in the way such that your IDE can't just collapse them all if you don't want to see them. In that case, I'm usually forced to give up. Lesson learned – always ask for the engineering team's stance on comments when interviewing!
lamontcg 3y ago
I recently wrote an ODE IVP integrator in C#. In the process I read the code in Numerical Recipes, Scipy and DifferentialEquations.jl. That combined with my own house style and some gyrations for allocation-free code resulted in the final product. A lot of what I took was just how to abstract the code into a few different layers to make it a bit more pluggable so that now I've got swappable BS5 and DP5 integrators. That layer structure came mostly from scipy. Some of the details of DP5 and the PI stepsize control came from NR. Not a whole lot came from the julia code since it is honestly kind of a mess due to what needs to happen for performance there. I did dig into it enough to find out that they're just using bisection with left/right endpoint control for events, so I used that which was much simpler than trying to sort out what endpoint control with Brent's method looks like. Oh I took some tips of the overall shape of the events API from the julia code so that the events get the integrator itself injected into it, so events can tweak the integrator shape. Still got some details left that I need to clean up and flesh out the events API, but it is way better code than the slightly OOP'd wikipedia-quality code that I was using. It should be flexible enough to drop other RK methods into it and even drop non-RK IVP solvers into it. Reasonably happy with the result and it is a lot better for having looked at other code and not continued to pursue NIH syndrome.
eternityforest 3y ago
What's interesting to me isn't code itself, it's APIs and user interfaces. For any given API there's multiple ways to implement it. But they often perform the same. If my goal was "Good code" I'd probably review and debate the value of each possibility. But I'd rather have any random trash behind a well designed API with unit tests, and then optimize it, instead of make a beautiful implementation with no real abstraction or tests or profiling. I'd rather have average code in Dart or Nim or Rust than great code in C, unless the performance was too critical for that. I'd rather have a python stdlib call than some excellent original code. And if I think the actual purpose of the code is stupid, I'm probably not going to care about how it's written. Reading code seems in theory like a worthwhile activity. But without hard science how can we be sure the time wouldn't be better spent reading actual literature and reminding ourselves that there's more to the world than code? Programmers write code a lot, and read it too, it's part of the job... Do we really need to do even more of that? If there's something particularly interesting I'll read it... but most code is not written like literature. It's written to implement something without anything surprising or innovative. Literature generally makes you feel something other then "Yep those are definitely words".
eternityforest 3y ago
What's interesting to me isn't code itself, it's APIs and user interfaces. For any given API there's multiple ways to implement it. But they often perform the same, and many of them are pretty OK. If your implementation is bad sometimes it's because your API is bad. Or the whole project shouldn't be done at all. Or you're dealing with essential complexity and no matter how many hours you refactor, nobody but a mathematican will think it's easy to understand, and if you really want to improve at it, shouldn't you be studying math instead of reading code? I'm not here to write amazing code, I want to make applications that can be maintained. If you pay attention to code all day, you're doing "pure" coding more than "applied" code.
pxc 3y ago
> Since I had my epiphany we’ve had several meetings of the code reading group, now known as the Royal Society of Twitter for Improving Coding Knowledge, along the new lines. We’re still learning about the best ways to present code but the model feels very right. Damn. Sounds like Twitter was a cool place to work, learn, and grow as a developer in 2014. It's wild to think how different it looks today.

219 points by fanf2 3y ago

svat 3y ago

A great companion read to this piece, diving deeper into one of the anecdotes mentioned, is "Reading Programs with Donald Knuth" (2018) by Dylan Lederle-Ensign: http://www.dlederle.com/2018/11/25/reading-programs.html http://www.dlederle.com/2018/11/25/reading-programs.html Seibel mentions here that of his Coders at Work interviewees, only Knuth and bradfitz did a lot of reading of other people's code, and later his insight that Knuth's reading style was not passive, and more like a "scientific investigation". This post goes into more detail about a concrete example of "reading", very similar to the one in the post (about the Fortran compiler for Bunker Ramo 300, that he read without knowing the operation codes): this one is about a program where again Knuth reconstructs "a listing of Whirlwind opcodes based on the program listing". I think seeing the actual details of what "reading" code entails—the specific margin notes etc–is very illuminating. It is also probably no coincidence that Knuth came up with literate programming (not only is he a writer at heart, he was a seasoned reader of other people's code, that too machine code!), and also somewhat addresses the complaints about Knuth's own examples of literate programming seeming unreadable: his threshold for what counts as "readable code" is different; code is not expected to be read like reading a novel but more like (his way of) reading a technical paper.

ozim 3y ago

Bad part is - as a young dev I was into Knuth and Uncle Bob and formatting code in beautiful way so someone who reads it is not amazed but gets the ideas what and why instantly. Worse for me was realization that we don’t speak the same language with people and making ‘a + b*c’ does not mean really much for people and they rather nag that I am not using spacing uniformly. So I declared bankruptcy on intelligent code writing and became brute as others so I don’t even care how variables are named I will just debug it 5 times or more with different inputs and I will know for sure what the code does. Keep in mind Knuth and Bob Martin come from old school where you had to wait long for getting your code run - nowadays I can run locally code multiple times and find out what it is doing on the spot … so my point code or beautiful code means a lot leas in daily work than 40 years ago…

Sparkyte 3y ago

Eh I would propose it is. Just not literature for everyone. You wouldn't go around saying something written in Japanese is not literature because it is a different language and follows different rules to read it. Same applies to a programming language, you need to be able to know how to read it to know what it is doing. You don't need inline comments, unless there isn't enough clarity in the code itself and someone shouldn't bend over backwards to sacrifice performance over readibility.

elihu 3y ago

I think most code doesn't really stand on its own very well. In order to understand it, you need to know a number of other things that might not be obvious (especially if the code in question has bugs, or has been rewritten a number of times and has some historical relics from earlier designs that are no longer relevant): What is this code supposed to do? What is the general execution model? What are the rules the implementation must follow in order to maintain correctness? The way code is written, it starts first as a collection of ideas, and then it takes concrete form as code. Reconstructing the ideas from the code may be possible, but sometimes it requires some extra help. Some things are best explained in English (or some other preferred native language) as ordinary written text. Some things are best explained as state transition diagrams. And some things can be expressed most clearly and concisely as code.

code_thr 3y ago

Code is literature. It's just that most of us are writing the equivalent of the Complaint tablet to Ea-nāṣir rather than Gilgamesh.

pflanze 3y ago

Previous discussions: 240 points|10 years ago|83 comments https://news.ycombinator.com/item?id=7091495 https://news.ycombinator.com/item?id=7091495 112 points|6 years ago|65 comments https://news.ycombinator.com/item?id=13855185 https://news.ycombinator.com/item?id=13855185 66 points|4 years ago|13 comments https://news.ycombinator.com/item?id=20667467 https://news.ycombinator.com/item?id=20667467

phibz 3y ago

I tend to treat code more like poetry or music. Its a shorthand for instructions telling the computer what to do. Depending on the language, naming, structure, and comments the original thesis may be lost or hard do understand. And in isolation short snipets don't often mean much or can change their meaning without context.

naruhodo 3y ago

After years of doing software maintenance of other people's code, my doc-comments have grown longer and longer. Software maintenance is often the kind of reverse-engineering challenge that Knuth describes in the linked article. I hate ambiguities and mysteries in code. I make it my mission to provide a complete mental snapshot of the domain knowledge required to understand anything I write. My doxygen doc-comments of C++ namespaces and classes have grown to the length of short blog posts containing a comprehensive introduction and overview to the topic, replete with links to external references. Some programmers probably hate me for this. Maybe a few love me.

kitanata 3y ago

[flagged]

meltyness 3y ago

There's legitimate tension here. With FOSS, the common desire is to build fix or modify, but frequently non-code explanations are sparse. That's one place where code reading is certainly desirable, and obviously the reverse engineering described.

parentheses 3y ago

Name code every programmer has probably read? My answer: Carmack's fast inverse sqrt

sinuhe69 3y ago

When it comes to reading code, the real question isn't just why—it's about when we do it, what we read, and how we go about it. As programmers, we all know that reading code is valuable, and we often tell ourselves we should do more of it. But let's be real, life happens and we don't always get around to it. One big reason? Time—or the lack of it. Unlike writers who can afford to read day in and day out, our job is to write code. So, when do we actually read code? Usually, when we need to. It might be diving into an API's documentation or snagging a code snippet from Stack Overflow to fix something. But here's the catch: once we figure it out, we tend to forget it. That's why if you asked me what code I read last week, I'd probably draw a blank. Sure, we do some reading here and there, but I think we should step up our game. When we solve a problem, we pat ourselves on the back and move on. It worked, right? But here's the thing: we can learn a lot by peeking at how the experts do it. Think of it like reading a book. We don't just skim the words; we dive into the plot, dissect the characters, and think about what makes it tick. Learning from others' code isn't all that different. When I started learning F#, I was blown away by the variety of solutions out there, all doing the same thing in completely different ways. Comparing them with my own attempts taught me a ton. Bottom line, we should always keep that student mindset. Don't just glance at code—study it. Pick it apart, understand its structure, and figure out why it's built the way it is. Whether you're a seasoned pro or just starting out, approaching code with fresh eyes can unlock a world of ideas. So, let's make time for it, even if it's just a little bit. It's an investment in our growth, our skills, and our identity as programmers.

kunalgupta 3y ago

i should never have smoked that shit now i can’t stop seeing everything manmade around me as literature

silviot 3y ago

Oh, this is by the author of "Coders at Work". I can recommend that: a good read!

messe 3y ago
And Practical Common Lisp, another popular one on HN. The domain name took me by surprised and I struggled to remember why it seemed so familiar; it turns out that PCL can be found in its entirety here, and I had used it years ago to learn CL: https://gigamonkeys.com/book https://gigamonkeys.com/book

imachine1980_ 3y ago

(2014), my lord

gwbas1c 3y ago

> The biggest lesson so far is that code is very dense. A half hour presentation is just enough time to present maybe a dozen meaty lines of code and one main idea. It is also almost certainly the case that the presenters, who have to actually really dig down into a piece of code, get more out of it than anybody. But it does seem that a good presentation can at least expose people to the main ideas and maybe give them a head start if they do decide to read the code themselves. Which exposes the disconnect: A computer program is not about expressing an idea; it's about doing a thing. It's a very specific set of instructions that explain how to do a thing; often having to handle corner cases that a human would not need explained to them.

ilrwbwrkhv 3y ago
100%. A lot of new programmers who didn't program back in the day have been used to this idea with abstractions and "clean code" and that causes so much issues these days. Instead the mental model should be how does the computer achieve the thing that I am trying and how can I make that happen with the fewest lines of instructions as possible. A computer program is an instruction set as you rightly said. It is not a long winded story with many "nouns" (objects).
- mochaki 3y ago
  [dead]
- pixl97 3y ago
  >t I am trying and how can I make that happen with the fewest lines of instructions as possible Isn't that the compilers job?
  - gwbas1c 3y ago
    The compiler doesn't know how to reduce three database round trips into one database round trip. Modern compilers are awesome, but they still can't read your mind to understand your intent and suggest changes that would objectively change the program, but do what your intent is in a much better way. Perhaps someday artificial intelligence could, but I think that is a long ways off.

wduquette 3y ago

> As I prepared my presentation, I found myself falling into my usual pattern when trying to really understand a piece of code—in order to grok it I have to essentially rewrite it. I’ll start by renaming a few things so they make more sense to me and then I’ll move things around to suit my ideas about how to organize code. Pretty soon I’ll have gotten deep into the abstractions (or lack thereof) of the code and will start making bigger changes to the structure of the code. Once I’ve completely rewritten the thing I usually understand it pretty well and can even go back to the original and understand it too. I have always felt kind of bad about this approach to code reading but it's the only thing that's ever worked for me. This has also been my experience over the last thirty-odd years, whenever I have to take over maintenance of someone else's code.

csours 3y ago
There's probably a better way to say this, but here goes: Anything you learn before you start working on something is familiarization. Familiarization is important, but it is not working knowledge or understanding.

retrac 3y ago

The right analogy is not to literature, but schematics of the architectural or mechanical kind. Those can also be beautiful, works of art, and objects of study. Sometimes a clever blueprint will allow seeing some aspect of construction that isn't otherwise obvious. But the prints are not usually the centerpiece for a discussion in their own right. The object depicted - a building or whatever - is the main focus. Going back to the literature analogy, reading groups are for fun (usually). Spark ideas and discussion. Code is too low level. It's like discussing the author's grammar and word choice -- sometimes necessary to understand the meaning of the text! - but most would prefer to discuss high level themes in the work.

agentultra 3y ago
Even then I would say code is not the blueprint but an artifact. Specifications of the precise, formal variety are more akin to blueprints [0]. They allow us to see the design of a system at a high level while eliding unnecessary details. Source code for programs are limited in that they can only express ideas about their local state. Barring high-level languages with dependent-type systems it is nearly impossible to model and check that your transaction consensus protocol works as intended without getting into a ton of gory detail... much more so if you want to check global properties of the concurrent system you're designing. I think Sussman was right: we often start with a pure model of what we intend to design but the artifact we produce, the source code of the actual program, is usually full of details that only matter to get the program to produce the expected behaviour when executed... and all that extra detail tends to drown out the core ideas. [0] https://cacm.acm.org/magazines/2015/4/184705-who-builds-a-house-without-drawing-blueprints/abstract https://cacm.acm.org/magazines/2015/4/184705-who-builds-a-ho...
- jll29 3y ago
  Along these lines, the perfect programming language would be one that eliminates all boilerplate that can be eliminated, one that leaves behind "pure design". "The result of the execution of the blueprint is the building."
temac 3y ago

lincon127 3y ago

[flagged]

Koshkin 3y ago
I think 50% of my coding knowledge came from reading other people's code.
- lincon127 3y ago
  [flagged]

falcolas 3y ago

The main argument appears to be that code is best dissected and understood, whereas literature is not? There's a fair number of philosophical texts which would disagree. Even "simple" engineering/physics/mathematics/science books often require a deep understanding, even though they're describing something, not providing directions. It's also often important to understand the context in which a piece of literature was written, just as it is important to understand libraries and the runtime context. In other words, I think it's fine to think of code as literature, just perhaps not the same literature the author frequently reads.

Sparkyte 3y ago
you decompose literature by dissecting it so the article is moot I agree
Supermancho 3y ago
> The main argument appears to be that code is best dissected and understood, whereas literature is not? There is no reference to "best". The issue is why codebases are not read as often as developer culture has doggedly engrained that it should be. A codebase is not enjoyable as a narrative or mechanically instructive, as you have implied due to the large number of confounding factors and approaches available. Literature is primarily a form of communication, while code is primarily a means to perform. It does not fit as "useful" literature. Most of the time, reading a codebase is like reading a manual that's faded and torn and was 500 pages long (now 486). You might learn something, (fast inverse sqrt and such) but this is as incidentally useful as a pithy wisdom buried on page 322 of a VCR Manual. Nothing about why they wanted to specify 2 buttons in tandem to eject the cassette^ or why it has cooling off instructions^^. ^ The build system/factory was making a similar device that required 2 buttons so management saved some money. ^^ The rewinding mechanism tends to heat and kill the whole device for a time. The original rewinder didn't fit the case 4 weeks from production, so a primitive replacement from a vendor was used which has this problem.

taeric 3y ago

Interesting to consider this in the light of how Knuth intends literate programming. Specifically, his version of "literate" is specifically dissecting the code for presentation. Sometimes you show broad strokes of the overall structure of the program you are presenting, but most of the time you dive into the details. It is funny as most of the time the big complaint is that there is still code there. It is not uncommon for the code to start with a section showing a basic C file with some standard includes at the top. And those will sometimes just have a shorthand C comment embedded in them for why they are there. This seems to frustrate many that think the entire thing has to read like a novel, but it makes perfect sense in the "dissected program" presentation of the code. There was a fun video I saw once of Knuth "critiquing" the code of his class. He called out liking the way first person was defined for use in the prose section and would spend time talking about the different stylistic choices of things. I'll have to try and find that again.

RaoulP 3y ago
Please do, I would be interested.
- taeric 3y ago
  I found https://www.youtube.com/playlist?list=PL94E35692EB9D36F3 https://www.youtube.com/playlist?list=PL94E35692EB9D36F3, which is a giant list of all lectures. I can't remember the specific one I was thinking of. There are a few there that are titled writing and literate programming. I'm guessing it is one of those, but I don't have time right now to watch them and confirm.
  - RaoulP 3y ago
    No problem, thanks!

gavinhoward 3y ago

I am one of the programmers that like to make dissectable code. In fact, I've included a whole manual, with my most famous project, that is entirely about dissecting the code. [1] And I will certainly do the same in my current project. Some of the most delightful moments I've had are when someone emails me with questions that indicate they've read my code, such as mentioning specific comments or asking about something in that dissection manual. I consider it a badge of honor if people think my code is good enough to study. [1]: https://git.gavinhoward.com/gavin/bc/src/commit/75cf2e3358b5/manuals/development.md https://git.gavinhoward.com/gavin/bc/src/commit/75cf2e3358b5...

alexvoda 3y ago
Just had a look. That is a wonderful intro document for your code base.
- gavinhoward 3y ago
  Thank you very much!
Pr0ject217 3y ago
Inspiring
hinkley 3y ago
I think if we sat over beers we’d find some common ground. I sometimes like to think of good code as short stories. Badly factored code is like a novelization of a story. Too long with too many side quests and you only find out at the end that the butler didn’t do it. Whether that pleases or infuriates is a gamble. Excessively terse code that requires broad life experiences to unpack? It’s interpreted by every observer to mean something different. Like a haiku, or even a song, the story being told is unclear. Beautiful, moving, but unclear. I much prefer short stories. A little flavor text, but no time for more than two clever ideas at once.
- ljm 3y ago
  when you think you have a good story to tell you will make it work no matter what. Epic poems like The Iliad or Baghavad Ghita or the bible are not immaculately retold from scratch but depend heavily on repetition and context cues. Code is the same.

WillAdams 3y ago

I believe: http://literateprogramming.com/ http://literateprogramming.com/ and the publication of: https://www.goodreads.com/book/show/499934.Computers_Typesetting_Volume_B https://www.goodreads.com/book/show/499934.Computers_Typeset... https://www.goodreads.com/book/show/1746886.Computers_Typesetting_Volume_D https://www.goodreads.com/book/show/1746886.Computers_Typese... https://www.goodreads.com/book/show/8981752-physically-based-rendering https://www.goodreads.com/book/show/8981752-physically-based... would argue against this. Esp. see: https://www.goodreads.com/book/show/112245.Literate_Programming_Volume_27_ https://www.goodreads.com/book/show/112245.Literate_Programm...

toby- 3y ago
The article does mention Knuth, the author of three of the books you mention.
- WillAdams 3y ago
  I think it would be more accurate to say the "most code is not literature" since it is not documented in a fashion which makes it readable --- and it would be more interesting if the examination/re-writing of the code was done in a literate fashion. The largest project I ever did (typesetting back-end for an on-line interactive ad design system) was done as a literate program, and over the course of years of maintenance was far easier to work with than other smaller code bases which I hadn't taken the effort to so structure and document. Arguably, I need to re-work my present project thus: https://willadams.gitbook.io/design-into-3d/ https://willadams.gitbook.io/design-into-3d/

thenoblesunfish 3y ago

I realized something perhaps similar which is that math is not literature. The only way to really learn anything is to go back and forth between reading and doing. Reading through a giant piece of code feels a bit like reading a math book and not doing the exercises. You'll get some good ideas and overview, but you won't really get "it".

eterevsky 3y ago

This is a bit weird to me since I never thought someone would just go and read source code of some program from start to finish. It would be something like reading an encyclopedia starting from the letter A. That said, I personally DO read code. Besides code reviews that were mentioned in the article I read the code that my code depend on. Especially when I want to better understand some API, I read not only the headers, but the actual implementations of the functions that I'm using. Sometimes I read code to better understand some algorithm. I only understood how Transformer architecture worked when I read some of its implementations. So yeah, reading code is cool. We just don't read it as we read books.

LeanderK 3y ago
yeah, weird. I read a lot of code. I often read code to exactly understand what's going on, how specific functions are used or how the API was intended to fit together. That may mean that I read random code on github, code of my dependencies etc. But it's not a continuous reading of code. I don't read the code of my dependency from start to finish.
Joker_vD 3y ago
> someone would just go and read source code of some program from start to finish. Well, one has to start reading from somewhere, and the start seems like a good way to start, is it not? Well, actually, no, it's not, because you have to waddle from main through like ten levels of procedure calls until some actual work starts being performed, but if you don't know where exactly the interesting parts are the only other options are either try to grep (doesn't work reliably in repositories where the authors like short and cryptic names) or to read source files until you find the relevant place. > It would be something like reading an encyclopedia starting from the letter A. I actually did something similar as a child, except I'd just open it on a random page and start reading. There is nothing really wrong with that as a recreational reading IMHO.
- kaba0 3y ago
  I remember there was a blog post saying that everyone should write an ARCHITECTURE.md file as well for their projects. It’s content can be a great starting point(s).

dimal 3y ago

I still think it's literature, just that most of it is trash literature. But then again, I was an English major and was trained on how to dissect literature. I realized a while ago that there was a book and a method I learned in English Lit 101 that I think informed how I read code. It's called The Critic's Hornbook, by William Dowling [0]. In short, it's a methodology for meticulously breaking down the meaning of every word, phrase and reference in a text, without resorting to any subjective interpretation. He showed us how, with proper understanding and research, you can find a lot of latent information about what's going on in the text. I find myself doing something similar when I read code, and when I write code. Code reading is also archeology. There are always layers of code accumulated over time, and you can start to see the minds of the people from years ago. And if you understand the constraints they were under and the assumptions they had, then it can help to understand "Why the hell did they do it _this_ way?" [0] https://www.amazon.com/critics-hornbook-Reading-interpretation/dp/0690008848 https://www.amazon.com/critics-hornbook-Reading-interpretati...

wglb 3y ago
Sounds like you are invoking Sturgeon's rule.
- dimal 3y ago
  I suppose I am. I think I’ve so fully internalized that idea that I forgot it’s not my idea!
foundart 3y ago
> it's a methodology for meticulously breaking down the meaning of every word, phrase and reference in a text, without resorting to any subjective interpretation How many words have only one meaning? In the presence of words with multiple meanings, how does one non-subjectively choose the meaning to apply to a particular usage when dissecting a particular work? I'd love to hear more.
- dimal 3y ago
  It’s been a long time since I did it at school, so I think what I do with code is more “informed by” that process than a duplication of it. But one specific thing I remember was that you look at context. One example I remember from school was reading The Love Song of J. Alfred Prufrock, and how by describing the fog as yellow and a few other details, we could infer that the setting was almost surely London, although that’s not stated. Another fun thing was reading old literature at looking up word after word in the OED to understand what a given word meant at the time that the text was written. This was a mind-blower. All these sentences that seemed very pretty but kind of confusing suddenly became very clear when you interpolate the older meaning. And then every clue you get builds up more context that you can use to infer other aspects about setting, character, etc. So, I think there is a fair amount of inference, but it should always be logically and objectively grounded.

lifefeed 3y ago

I like to distinguish between Programming and Software Development, even though I don't have precise definitions for them. Programming is what you find in code samples and books and tutorials, where the code is clean is readable, and is what most of us fall in love with. Software Development is all about diverse and messy and malicious inputs and outputs, and the code is filled with the hairy edge cases[0], and it is not fun to read, but it is what most of us get paid for. 0 - e.g. the classic https://www.joelonsoftware.com/2000/04/06/things-you-should-never-do-part-i/ https://www.joelonsoftware.com/2000/04/06/things-you-should-...

aatd86 3y ago

Is a cookbook literature?

Supermancho 3y ago
I would say so (not the same as a recipe). In this way a recipe and the ten commandments look the same. Reductionist comparisons are pretty easy to make. Sometimes code and recipes look the same, if the codebase is small enough and both omit the deployment/build chain/tooling in favor of implied requirements.
- aatd86 3y ago
  What's the difference between what is literature and what is not literature then? I realize I was taking for granted what literature was? (I have an idea but I will add it later)
  - Supermancho 3y ago
    As far as I can tell, literature is a form of explicit communication to the naive reader, which intrinsically provides context to interpret it. The README is literature. The code is not (common case). A cipher is not literature, even if that cipher is breakable, resulting in literature. It may be useful to consider it literature if you know the cipher, but it is not until that transformation has occurred. You may recognize this if you try to read a story written by a child or mentally disturbed individual. The story might skip or be interrupted/incomplete or is otherwise nonsensically mangled structurally and narratively. Literature implies literacy to access the medium both ways (reader and author). Broken manuscripts are not literature, per se. Literature is a soft term, so what I think holds no value other than how it might well describe the populist zeitgeist surrounding the term.
    - aatd86 3y ago
      So literature is a communication form while code is information (i.e. What's being communicated)? Makes sense.

tabtab 3y ago

2B || !2B

the-printer 3y ago

> Seibel: I’m thinking of the preface to SICP, where it says, “programs must be written for people to read and only incidentally for machines to execute.” I’m wondering if the initial statement in SICP spoke from a time that was similar to a 1977 McGraw-Hill textbook, “Introduction to Computers”, that I picked up from a thrift store recently. A significant portion chapter on developing computer programs is dedicated to methodology; planning, the development life cycle, systems design, instructing users, processing methodology. The next chapter is about flowcharts and tables. I mention all this to point out how intrigued I am by what looks like the emphasis that was placed back then on clarity from the human’s perspective, be it programmer, user or anyone else involved in the software’s development and use. Another thing that’s interesting to me is how old code like Fortran looks like it’s made up of mostly just words, compared to modern languages I’ve looked at that use a lot of abbreviations and special characters. My knowledge of programming and its history is excruciatingly minimal, but this blog post and that excerpt sort of remind me of what I just mentioned. I’m not sure why exactly, or if there’s any credence to it.

wduquette 3y ago
I've spent a lot of time trying to make sure my code is commented and easily readable; and I haven't found any of that time to be wasted. I've often had to go look at code that I wrote two years, or five years, or twenty+ years previously, and I've greatly appreciated the work I put in when I wrote it.
SoftTalker 3y ago
The approach in 1977 was that the problems we address with computer programs were static. It was up to the system developers to understand the problems well enough to learn their requirements and then implement the requirements as code. Writing the code was the last thing you did, after the problem was entirely understood, documented, flowcharted, signed off by the client, etc. Now we understand that the problems often change as the code is developed, or in response to the code we develop. Priorities and requirements change as the work proceeds. We start writing code early, solving small parts of the problem, and building up a solution almost organically, the way a tree will grow around obstacles in its pursuit of sunlight. The name Fortran is a contraction of "Formula Translation" it was developed to be usable by mathematicians and scientists. COBOL is another language that looks very wordy, as it was developed to be used by businesspeople.

gilessbrown 3y ago

Code isn't really literature. It's more like a contract. It needs to be intelligible and clear because it will be taken more literally us humans can generally imagine.

beardog 3y ago

I argue that (good) literate programming can make code literature. Your program is told as a sort of story and ought to contain background info, thought processes, and rationale for decisions. Additionally macros can be used to reuse code at build ('tangle') time that your underlying language may not otherwise support. For example if I have some constants i need throughout a python program, I might put it in something like constant.py during normal programming, but if I were literate programming I could have a section called "Program constants" and dive into each one, referencing them with macros throughout the program. You do have to be careful because the macros can make debugging confusing since you are now working with two languages instead of 1. You can also put stuff that is irrelevant to humans out of the way of the most important stuff. Example literate program for writing a virtual machine program (not my work): https://www.jmeiners.com/lc3-vm/ https://www.jmeiners.com/lc3-vm/

pxc 3y ago

I read code for fun sometimes, but it's usually not whole codebases. I like to read PRs that I think are exciting in projects that I use, and then branch out to the context that they're invoking or changing as well. I've never thought of it as something I do to advance myself as a programmer, though. I just kinda do it on impulse, and I'd still do it even if I found out it didn't really improve my skills. Anyone else recreationally browse PRs in F/OSS that they use, kinda like reading the news?

atomicnature 3y ago

It is a new kind of literature, with the key characteristic being "dynamically sequenced reading". Unlike literature, code is supposed to be read in an order most conducive to the reader's goals, rather than the author's goals. Also, unlike literature, often new code is built upon old in an explicit and direct way. Although even in literature, one builds on top of old ideas. I think Peter Norvig once commented on why Knuth's Literate programming didn't catch on. His guess was that, people usually have a specific purpose when they are looking into a piece of programming, and they want to read it in an order most suitable to them. With LLMs, there could be dynamic code exploration helpers, I think. They could take our goals, and then introduce parts of the code that are relevant to the reader, with extended guidance...

bregma 3y ago

The premise is wrong. Well, it's not wrong, its just that it's premised on the definition of 'literature' being 'high brow writing for the elite' in the sense of something that can be dissected and analyzed for the sole purpose of revealing something about the human condition. It's true that computer program code is not that kind of literature and no fine arts major is likely to ever write a graduate-level thesis on it expounding the symbolic allusions to the Christian Bible and how it represents society's fear of death and desire for sex. Source code is, however, literature in the sense that it is written for people to read. Not for computers to read. People. Sometimes other people, often the original author at a later date, but people nevertheless. By definition, that makes it literature.

lifeisstillgood 3y ago
completely agree. Even writing a book on "software literacy". A small side note - most of us will know a manager who "used to code but stopped when went into management". But none of us know anyone who stopped reading and writing English (German, Japanese) when they went into management. The difference might be that we don't have many companies that can be managed with code, or that a lot of people in management don't need to be there. Edit: VW is an interesting case in point. It does not matter what a manager says, what the design document lays out. what matters is what the code says. And VW CTO knew this so he made the commits to the code base that tricked the emissions tests. That is management-by-code.
deleted 3y ago
[deleted]

egonschiele 3y ago

I'll present a different take. There are some basic things you can do to make your code more readable: - avoid double negations - use grep-pable names and avoid string interpolation - keep code duplication if that version is more readable and maintainable. I'd love to see a longer list. In my experience, engineers too often code as if keeping the code as short as possible is what matters, instead of optimizing for code that is easy to read.

javier_e06 3y ago

The headline makes me reminisce of a object oriented class I had years ago. The instructor asked: "If you are coding a black jack game, who shuffles the deck?" The dealer we all responded. "I daresay that the deck shuffles itself" the instructor replied. In Literature that is impossible. Unless you are reading Alice In Wonderland.

creer 3y ago

Code is rarely meant to be read. Even when we have to read the code to sort out some problem, or to reuse the principle at the core of it, reading is hard enough. One eggregious example that comes to mind was code released with all comments stripped out and largely obscure variable names.

InitEnabler 3y ago

For me code may have elements of syntax like literary language, its primary function is to convey logical instructions and operations. imho.

hnfong 3y ago

I think the comparison is a bit "unfair". When writing was first invented, it was presumably, mostly for functional purposes. Keeping records; Calculating taxes; Government administration; etc. If one looked at writing at early stages of development, one could very well come to a similar conclusion that "Writing is not literature". And that still is true, mostly. Writing generally is not literature. Just look at the comments under a Donald Trump video for example. Not sure anyone would want to read those. In fact I'm pretty sure <0.1% of the comments here in HN would qualify as "literature". But if you said "Writing is not literature", despite it being true, it's probably misleading. The term "literature" is generally reserved to the finer styles of writing that in addition to whatever functional purpose it served, had an aesthetic to it that makes it worthwhile for others to read. Most literature comes from a long tradition where styles and techniques are developed to make the text more interesting and pleasing. The traditions and the corpus of literature grow stronger as time goes by. Of course, best works accumulate and are archived for future generations to study as well. This has gone on for thousands of years for "natural language literature". It has a head start of thousands of years. Code has been invented for less than 100 years. That's nothing in the greater historical context. Imagine digging up ancient clay tablets of which 99% talk about how much bales of barley we need to collect to feed workers next year, and concluding that this language/culture is not capable of literature. That's what the article is arguing essentially. But do we have evidence otherwise? Are there code so aesthetically pleasing (or at least interesting) that it might be read just for pure joy? Yes there is. Just not a lot. For example, check out the entries of IOCCC. Some of them are insanely beautiful, and I have no idea how the authors could have created them. They're the equivalent of carefully written poems in C, except they're possibly even harder to write. So yes, while I agree that the article is probably literally correct in saying (vast majority of) code is not literature, I think it's wrong to interpret that statement as "code can't be literature". It obviously can be in a substantial way. It's just that the cultural norms haven't caught up yet, and while people today somehow think they become more "refined" after reading for example Shakespeare (which I have no idea why besides gatekeeping attempts from the elite class), the programmer class hasn't yet taken over schools to shove quick reverse sqrt (0x5f3759df - ( i >> 1 )) down student's throats and call it a well-rounded education. (Tangent: yes, all the things you felt were useless in school are probably really as useless as understanding Q_rsqrt, i.e. not very useful unless you really need it, but 99% people don't really except for showing class status) I grant you that I can't think of any equivalent to long form novels that might work in code, since telling and listen to stories are somehow baked into basic human psyche for which code has no equivalent, but literature is more than novels so I'd claim at least code can be a meaningful subset of literature.

vaughan 3y ago

Code should be more like a children's popup book with little tabs to pull on to make things move around. When I look at a foreign piece of code I want to see all the runtime values inline in my editor and a time-travel debug session with a slider and a stack trace of the function under my cursor, and a trace of the _value_ under my cursor showing every transform that happened to it, and all common data structures and their algorithms visualized and animated in appropriate diagrams. And available in all our tools instantly - like when viewing code on Github.com. I really think you could figure out what is going on with most code if you simply move a slider back and forth and watch everything that changes. And it would be much more fun with a physical knob to turn (e.g. https://www.tourboxtech.com/ https://www.tourboxtech.com/ or https://www.binepad.com/product-page/bnr1-v2 https://www.binepad.com/product-page/bnr1-v2). Knob-driven development :D

darkmarmot 3y ago
Have you tried doing this with distributed computing? It's not very feasible...
- vaughan 3y ago
  Local simulation + deterministic record-replay.
scottlamb 3y ago
Heh. I think you have the absolute opposite viewpoint from Rob Pike, who said of syntax highlighting [1]: > When I was a child, I used to speak like a child, think like a child, reason like a child; when I became a man, I did away with childish things. I'm with you! That sounds awesome. I enjoy not only syntax highlighting but also type annotations and doc references on hover. I'd love to see even richer and more interactive stuff. [1] https://groups.google.com/g/golang-nuts/c/hJHCAaiL0so/m/E2mQ1RDiio8J https://groups.google.com/g/golang-nuts/c/hJHCAaiL0so/m/E2mQ...

m1n1 3y ago

One thing I've done in the past is put comment "tours" in the code so you can follow with your IDE's search. Each comment has the name of the specific tour, a number, and the tour guide's blurb. This lets the visitor follow a nice sequence, across different files if necessary... Sort of like the inverse of literate programming

ravenstine 3y ago
I'm all for using comments, but you have to be on a team that's on board with them. I've joined more than one team that adopted the "the code should be its own documentation bruh" attitude, as if comments get in the way such that your IDE can't just collapse them all if you don't want to see them. In that case, I'm usually forced to give up. Lesson learned – always ask for the engineering team's stance on comments when interviewing!

lamontcg 3y ago

I recently wrote an ODE IVP integrator in C#. In the process I read the code in Numerical Recipes, Scipy and DifferentialEquations.jl. That combined with my own house style and some gyrations for allocation-free code resulted in the final product. A lot of what I took was just how to abstract the code into a few different layers to make it a bit more pluggable so that now I've got swappable BS5 and DP5 integrators. That layer structure came mostly from scipy. Some of the details of DP5 and the PI stepsize control came from NR. Not a whole lot came from the julia code since it is honestly kind of a mess due to what needs to happen for performance there. I did dig into it enough to find out that they're just using bisection with left/right endpoint control for events, so I used that which was much simpler than trying to sort out what endpoint control with Brent's method looks like. Oh I took some tips of the overall shape of the events API from the julia code so that the events get the integrator itself injected into it, so events can tweak the integrator shape. Still got some details left that I need to clean up and flesh out the events API, but it is way better code than the slightly OOP'd wikipedia-quality code that I was using. It should be flexible enough to drop other RK methods into it and even drop non-RK IVP solvers into it. Reasonably happy with the result and it is a lot better for having looked at other code and not continued to pursue NIH syndrome.

eternityforest 3y ago

What's interesting to me isn't code itself, it's APIs and user interfaces. For any given API there's multiple ways to implement it. But they often perform the same. If my goal was "Good code" I'd probably review and debate the value of each possibility. But I'd rather have any random trash behind a well designed API with unit tests, and then optimize it, instead of make a beautiful implementation with no real abstraction or tests or profiling. I'd rather have average code in Dart or Nim or Rust than great code in C, unless the performance was too critical for that. I'd rather have a python stdlib call than some excellent original code. And if I think the actual purpose of the code is stupid, I'm probably not going to care about how it's written. Reading code seems in theory like a worthwhile activity. But without hard science how can we be sure the time wouldn't be better spent reading actual literature and reminding ourselves that there's more to the world than code? Programmers write code a lot, and read it too, it's part of the job... Do we really need to do even more of that? If there's something particularly interesting I'll read it... but most code is not written like literature. It's written to implement something without anything surprising or innovative. Literature generally makes you feel something other then "Yep those are definitely words".

eternityforest 3y ago

What's interesting to me isn't code itself, it's APIs and user interfaces. For any given API there's multiple ways to implement it. But they often perform the same, and many of them are pretty OK. If your implementation is bad sometimes it's because your API is bad. Or the whole project shouldn't be done at all. Or you're dealing with essential complexity and no matter how many hours you refactor, nobody but a mathematican will think it's easy to understand, and if you really want to improve at it, shouldn't you be studying math instead of reading code? I'm not here to write amazing code, I want to make applications that can be maintained. If you pay attention to code all day, you're doing "pure" coding more than "applied" code.

pxc 3y ago

> Since I had my epiphany we’ve had several meetings of the code reading group, now known as the Royal Society of Twitter for Improving Coding Knowledge, along the new lines. We’re still learning about the best ways to present code but the model feels very right. Damn. Sounds like Twitter was a cool place to work, learn, and grow as a developer in 2014. It's wild to think how different it looks today.