Kindergarten Code.Key
Total Page:16
File Type:pdf, Size:1020Kb
I wanted to give this talk because over the past several years I’ve come to appreciate a particular quality in code that I didn’t have a name for. But then I finally found a useful name: kindergarten code. ThisKindergarten talk is a collection of quotes from people much smarter than ICode to give you a sense of this “kindergarten code” and why it’s important. Shawn M Moore @sartak Your code should read like a smart kindergardener wrote it Brent Simmons – Vesper Sync Diary “Since this is a super-critical part of the app, it should read like a smart kindergardener wrote it. Which is exactly how I want all my code to look, come to think of it.” Your code should read like a smart kindergardener wrote it Brent Simmons – Vesper Sync Diary All the damn time I see code that’s confused and more complicated than it needs to be. It’s easy to fall into this trap. But if your code is clear and straightforward, enough that a kindergartener could understand it, then you’re in good shape. Code that looks like through some divine inspiration you got it exactly right the first time Bernie Cosell – Coders at Work “I want every routine you work on to look as if it was just written. I do not want to see any evidence of afterthoughts or things gone wrong followed by something to correct the error or a mysterious piece of code saying, "This routine returns the wrong value every now and then so I've got to fix it." I don't want to see any of that. I want to see code that looks like through some divine inspiration you got it exactly right the first time.” Code that looks like through some divine inspiration you got it exactly right the first time Bernie Cosell – Coders at Work Say as you’re working on something you realize a better way of doing it. You damn well better circle back and improve upon the existing code to use that new style too. You’ll see examples of this done poorly EVERYWHERE YOU LOOK. ! Do not comment out code. git will remember your previous versions. Code confidently! Divine inspiration… you know what, I actually like that better. Let’sDivine go with “Divine Code”. Code Shawn M Moore @sartak Build APIs that steer developers in the right direction Brad Abrams – The Pit of Success “Build platforms that lead developers to write great, high performance code such that developers just fall into doing the “right thing”. Rico called this the Pit of Success. It is the key point of good API design. Build APIs that steer and point developers in the right direction. Types should be defined with a clear contact that communicates effectively how they are to be used. I am not just talking about the docs and samples but in the design of the APIs.” Build APIs that steer developers in the right direction Brad Abrams – The Pit of Success I don’t love the term “pit of success” but I think it’s trying to be the exact opposite of “pit of despair”. But it is what I strive for when I architect something (success, not despair). Apple does a really great job of this with its APIs. There’s a consistency and clarity to the UIKit APIs that just makes you feel like a wizard. There’s an obvious, straightforward way to do things. APIs are orthogonal and work together. That’s why I love Objective C so much. Each time I figured out another step of the process I thought, “Wait, seriously?” And each time Microsoft implicitly replied, “Seriously.” Casey Muratori - The Worst API Ever Made An incredible example of where this was done wrong is described in http://mollyrocket.com/casey/stream_0029.html The author describes an API for a simple feature that basically took weeks to actually get working, because it was so horrifically designed. Don’t do this. Don’t require your users to care about weird implementation details. The takeaway from Casey’s piece is write your synopsis first because it will be free from those unnecessary details. Shorten the conceptual gap between the static program and the dynamic process Edsger W. Dijkstra – A Case against the GO TO Statement (EWD 215) “Our intellectual powers are rather geared to master static relations and our powers to visualize processes evolving in time are relatively poorly developed. For that reason we should do (as wise programmers aware of our limitations) our utmost best to shorten the conceptual gap between the static program and the dynamic process, to make the correspondence between the program (spread out in text space) and the process (spread out in time) as trivial as possible.” Shorten the conceptual gap between the static program and the dynamic process Edsger W. Dijkstra – A Case against the GO TO Statement (EWD 215) Your program is little more than a gigantic text file. When you run your program, the text isn’t itself doing anything. The process that results from your program is a living, breathing beast. It’s important that the program and its process match as closely as possible, otherwise it’s very difficult to understand and modify the program to get the desired behavior out of the process. Shorten the conceptual gap between the static program and the dynamic process Edsger W. Dijkstra – A Case against the GO TO Statement (EWD 215) It’s the difference between a recipe and its resulting dish. What you wouldn’t want in a recipe is nonsensical, extraneous steps. Like if you’re following a recipe and step 4 is flush your toilet. Why the hell is that in the recipe? Because the original guy had to take a leak while he was waiting for his noodles to boil. You might think that’s ridiculous, but it happens ALL THE DAMN TIME in code. “Oh I was trying to fix something so I just left that in there and didn’t bother to remove it when I figured it out that the problem was somewhere else.” Use “git add -p” to select exactly the changes that do what you need and throw the rest away. Trying to compress that rich picture over a very low- bandwidth channel Bret Victor – Media for Thinking the Unthinkable “The authors have a very rich picture in their heads. And they're trying to compress that picture to transmit over a very low-bandwidth channel, which is this stream of symbols. So it's a very lossy compression. And we've got the reader on the other end trying to decompress this picture into their own head. And it doesn't work very well.” Trying to compress that rich picture over a very low- bandwidth channel Bret Victor – Media for Thinking the Unthinkable This quote was talking about a scientific research paper, but it applies equally well to code. The programmer knows in their head what they’re trying to accomplish. They have to communicate this idea using the programming language. There’s no way to encode all of that rich picture into text. So to make sure that there’s no miscommunication, you want to be very precise, very explicit, and overly critical. I’d go so far as to say that you want to do this in all technical communication, whether it be code, tests, documentation, IRC channel, etc. Programs must be written for people to read Abelson & Sussman - Structure and Interpretation of Computer Programs “We want to establish the idea that a computer language is not just a way of getting a computer to perform operations but rather that it is a novel formal medium for expressing ideas about methodology. Thus, programs must be written for people to read, and only incidentally for machines to execute.” Programs must be written for people to read Abelson & Sussman - Structure and Interpretation of Computer Programs I’m sure you’ve seen this quote before. This is the same idea as the previous few quotes. It is VITAL that your code be comprehensible or it becomes a liability. Quick informal poll, has anyone had to modify code that wasn’t incredible? Did that go well? Do you wish the author had been more careful putting together that code? In less than a minute Dan found the methods involved, made the (relatively major) changes Alan Kay – The Early History of Smalltalk “Steve Jobs said he didn't like the blt-style scrolling we were using and asked if we could do it in a smooth continuous style. In less than a minute Dan found the methods involved, made the (relatively major) changes and scrolling was now continuous! This shocked the visitors, especially the programmers among them, as they had never seen a really powerful incremental system before.” In less than a minute Dan found the methods involved, made the (relatively major) changes Alan Kay – The Early History of Smalltalk This is an anecdote I like that reflects what having this clarity in your code. There’s a certain beautiful competence you earn by having your code well- formed and comprehensible. Anything that doesn’t live up to that beauty is offensive to me. If only you could read my private Slack conversations… :) The most depressing thing… is a chunk of code… you dare not modify Simon Peyton Jones – Coders at Work “The most depressing thing about life as a programmer, I think, is if you're faced with a chunk of code that either someone else wrote or, worse still, you wrote yourself but you no longer dare to modify.” The most depressing thing… is a chunk of code… you dare not modify Simon Peyton Jones – Coders at Work I’m sure no one here has been in this situation before.