6 ms·
Code Reading Club (2020)
- ramraj07 6y agoDeliberate code reading clubs especially in the way the author describes it is a great idea; it does seem like a rare gift to be able to dive into someone else’s (often not well structured) code and figure out how it works. One caveat is that in the end, especially for poorly designed code, there’s only so much you can mitigate or train someone on the fundamental requirement- how big a mental model can you instantaneously form about a new codebase? I’m not sure how much you can train someone to increase this metric.
- blunte 6y agoIf the code were particularly bad, or there were much better implementation approaches, that can spark a nice discussion which might actually teach more than simply reading good code. Postmortems of failures tend to stick a lot more than good examples :).
- dhosek 6y agoThis was part of the beauty of Knuth's Literate Programming concept: The code was meant to be read, rather than scanned. The ability to do things like replace blocks of code with ``` @<Description of what happens here@> ``` and then provide the description in a part of the .web file that made sense for talking about it made it possible to, for example, describe a complex algorithm in understandable steps, allowing the reader to then delve into the details of how those steps worked at a later time. When I wrote LP-style code, though, I liked to put my main method at the head of the file rather than buried somewhere deep as Knuth usually did, as it made it easier to give a high-level take of how the program worked. With modern coding, though, where things are broken down into modular chunks, LP, I think, breaks down. It's a lot easier to have a single readable weave-generated document when you have a single compilation unit. One of the things that turned me off of cweb was that I realized that my practice of putting the .h and .c files together in a single .cweb source file made sense for the presentation, it greatly increased compilation times since the .h file would be regenerated even if it wasn't changed which then meant that all the files that read the .h file would also be regenerated. Given that compilation times back in the 90s were a significant issue (and in many cases, we were in a single-processing environment), this was a big handicap. With a lot of modern coding, the biggest challenge is just finding a starting point for grokking the code. In a Spring application, for example, the main() method is literally the least interesting part of the code. Usually, I will look for a controller and start digging from there. Given the fact that so many of my co-workers seem unwilling to create simple readme.md files that talk about how to build and run code, I think it would be a lot to ask for them to provide a guide to reading the code.
- akkartik 6y ago> With modern coding, though, where things are broken down into modular chunks, LP, I think, breaks down. I wonder if it makes sense to blame our culture of extreme modularization here, rather than LP. Somewhere out there is a parallel universe where codebases are divided up into mostly linear chapters. The build system builds a hierarchical module tree out of it (in combination with compiler caches to speed up incremental compilation), but nobody actually looks at it. > Given the fact that so many of my co-workers seem unwilling to create simple readme.md files that talk about how to build and run code, I think it would be a lot to ask for them to provide a guide to reading the code. Well, there goes my idea :) Yeah, totally valid point. LP is perhaps more useful for those of us interested in practicing code exposition (with lots of secondary benefits) rather than as something for a whole org to buy into.
- dhosek 6y agoI was talking to a therapist recently about the team-oriented organization of software development and he found it incredible that things are organized that way rather than by individual work. Certainly, in the early part of my career, I worked much more autonomously. While tools like version control allow for greater collaborative effort, I'm not entirely convinced this is a good thing.
- sghiassy 6y agoReading code is one of the truly under appreciated skills in the software industry
- eyelidlessness 6y agoI like the idea. If people want to learn to read code and grow from it I highly encourage adopting tools suitable for that task. You can’t read code in a diff. You can’t read code in commits on GitHub. You can’t. You read code in an editor with reference navigation. And you go navigate even if the interface didn’t change. And you go read tests to see what they (don’t yet) exercise. You need a full dev environment to read. Again fully in support of the effort. Just want to make sure readers have context to embrace their tooling context for the task.
- xyzzy_plugh 6y agoI can't agree with this, generally. It depends on the language and the project. > You need a full dev environment to read. I don't. My "full dev environment" is just vim with stock configuration anyways. I read code on my phone everyday. I read code on GitHub every day. Does GitHub suck for reading code? Absolutely. But it's not impossible, far from it. I mostly read Go, C, various configuration dialects and she'll scripts, occasionally some Java or Python or Rust. Perfectly readable in plaintext. Sure Scala is borderline unreadable without an IDE but for the most part it's fine. I mean, after all, you can read code in a book, can't you?
- eyelidlessness 6y agoMy point is that you can’t know the full impact of a code change without the full context of the change. Just a silly, trivial example: someone opens a PR to change a brand color on a website’s theme. You see one line of code changed but the effect is probably far reaching. Now, using only a diff, you have to trust that either the tooling or the human or both have validated every usage under every scenario to identify regressions. Is some placement of that color now too low contrast? Is it too jarring in dark mode? Is it being used for non-brand purposes because someone got lazy, and changing far more than intended? How can you know unless you have the rest of the code base in your head? Do you trust your test coverage?
- hinkley 6y agoReading code diffs is like examining your life as the changes that happen over time but not actually examining your life. This is how you wake up one day and realize that you don’t like the person in the mirror, or that nobody else does. Aka “boiling the frog.”
- blunte 6y agoThe value of reading code depends somewhat on the language and context. Some languages are so expressive and low friction that they read as easily as we breathe air. And some contexts are so well understood that we already know what is going to happen in the code, assuming there are no bugs. Therefore, I would argue that a lot of code simply doesn't need to be read. If the problem it solves is understood and documented, and various approaches to testing prove that it does what it should do, then chances are the details of how it accomplishes that goal are largely uninteresting. What is interesting to read is more organizational approaches that can be used when solving a problem. For example, at the architectural level a solution can be a monolith or some collection of coordinated pieces (services). Here, the interest is in the decisions made and how they were implemented at a conceptual level. At the code level, things only get interesting when we want to take an uncommon approach (such as functional Ruby). Then the code can illustrate tradeoffs of the approach taken, and we can learn by studying and debating it. Lastly, performance constraints can make code "odd", and that can be worth studying. The standard boring ways of solving problems may not have been possible in a given situation, so some new or complex or novel approach was taken. But even here, the magic isn't really in the code; the code just implements that solution. It's probably more valuable to understand what implementation decisions were made and why. This is not to say that doing code reviews is a waste of time; it very likely will make you a better programmer. But time could be spent at a slightly higher level and make you a much better developer/problem solver. (Unfortunately it's not often possible to read at that level since a lot of that information never gets documented!)
- yuliyp 6y agoI don't find myself reading code for the sake of reading it. I'm usually trying to answer some questions, such as "how is this structured?" or "what might be causing buggy behavior X" or "how expensive is this" etc. That informs the things I pay attention to and the things I ignore. The way I read code is meant to optimize for question-answering and understanding (aka future question-answering). To that end, I've learned many heuristics, such as "pay attention to method signatures, look at what the loops iterate over, understand the call graph, skip over the error handling bits unless needed, etc. I don't view these as tools for helping me read, but tools for helping me gain understanding of code quickly and without wasting brain space on probably less relevant bits.
- Cthulhu_ 6y agoSame, but I just realized that doing code reviews is reading code; I haven't done that in a few years now, but it does make you think about how you yourself write code, so that was a valuable lesson.
- hinkley 6y agoThere's a Ben Franklin quote that I'd love to see applied to software. He was self-taught in writing and the way he got better was to develop a one person version of the 'clean room protocol', by relying on the fallibility of long term memory to separate himself from the source material. He would take an article he loved, try to write a summary of it, then put the summary and the article away. Later he would pull out the summary, and try to write an article to match, then compare his results. Put it away again, pull it out and write a new summary, then compare the summaries. There are a number of problems with writing a new library to replace an old one that cause us to commit most of the same mistakes, or recreate the mistakes of the old old library. Chesterton's fence and Anchoring being two big examples. This makes most new code evolutionary instead of revolutionary. The first time I saw this phenomenon for what it was had to do with attempts to target the JVM with other languages. This facility has essentially been in Java since 1.2, but the initial tools for doing so looked like assemblers, and not even macroassemblers. You were writing assembly by hand, without variables or registers (since the JVM is stack based). The next two attempts to do something better were less awful, instead of good, and my interpretation is that they were trying to fix something that was broken instead of building something new. A whole generation of devs missed out on leveraging that technology, and most of the work to make the JVM a better host happened after Sun Microsystems was no more. We get a jQuery or a usable macroassembler once a decade instead of twice a year. We aren't going to get hardware advances like the old days (Apple's "M3" will probably not be 3x better than the M1), it would be good if we could accelerate excellence in library design. TDD hints at a way, but I think we could go farther, and I have an intuition that such efforts could spin off of code reading groups, if they existed.
- akkartik 6y agoI loved this comment and also your https://news.ycombinator.com/item?id=26646153#26669166 https://news.ycombinator.com/item?id=26646153#26669166. I'm curious what you think of my https://github.com/akkartik/mu https://github.com/akkartik/mu