It's hard to write code for computers, but it's harder to write code for humans

This may be a cultural trait too. Erin Meyer in her "Culture Map" Book mentions this idea that every culture approach persuading others differently from theory-first to examples-first.

I agree. Many coding courses start with setting up your environment, where to download the base packages... I much prefer the core concepts first.

Well put, you beat me to it! Specifically this line started my disbelief:

  Humans don't learn about things this way.

Naturally, as is the hacker way, with no citations. I’ve only scratched the surface of pedagogy, but it’s a massive and mature academy drawing its modern principles from the empirical psychology of Dewey and Piaget. There’s a LOT more to say about it than can be covered in a blog post, much less a subsection of a blog post!

As you point out, the biggest issue is that people are different. The next biggest issue is we aren’t even sure why those differences occur, or how stable they are over time…

Well written post otherwise and it’s a good dive into the pragmatics of a particular educational strategy — I just would ask to see more humility, I guess!

I have the same (and ran into this trying to wrap my head around why Maven didn't work... I don't want a tutorial explaining how to get started, I need to understand the fundamentals to understand what's happening!).

I think, however, that starting from the examples might help with good API design: if you design your API to be "core concept first", this will likely lead to an API that _can only be used after you understand the core concepts_, which is not great when people are only occasional users.

I used to think I was a "core concept" kind of person, but later I realized I took that way too far and would refuse to do things outside of my comfort zone unless I felt like I truly understood everything ahead of time.

Nowadays I'm much more likely to just jump in and start working with examples directly, and I feel much more productive. It's partly a thing of trust: I just trust that the makers of high quality software have put in enough thought to make their interfaces easy to understand, for the common use cases, without digging too deep into the internals.

It frequently happens, of course, that I hit a roadblock where I do have to go deeper -- but that's only because there were 10 other things where I was successfully able to get by on surface impressions alone. So I find that even when I do dig in it's often time well spent.

how do you manage when the core concept are too abstract ? I guess then you would need some examples to understand ?

That's why there are four axes of documentation.

I cannot agree more.

I also want to add that I hate these "project generators" such as create-react-app when I'm just getting started. (It's just an example: I'm glad I learned React long before its existence.) They create an opinionated folder structure with template files and preconfigured tools. I don't function well in this model: if I don't immediately have a high-level overview of what the created files do, why they are created this way, I just become uneasy at all this magic that I do not understand. Each time a new thing is introduced, I need a high-level introduction covering its purpose that relates to the concepts I already know. I'm not comfortable dealing with magical black boxes unless I have at least a rudimentary understanding of the main interface of that black box.

To put this back into the concrete example, it means that hypothetically if I were to be learning create-react-app from scratch, I would immediately begin to investigate the purposes of the tools that have been configured by it, like Babel and ESLint.

I write very verbose tutorials ([0] has my latest effort). I walk through the reasoning, from start to finish, and usually use things like Git tags and releases, to support the prose. I also like to provide examples that are very “real-world.”

It doesn’t seem that people read it. I think folks prefer videos and unrealistically sparse examples.

[0] https://littlegreenviper.com/series/universal-links/

Tried that and don't know how I successfully studied computer science that way.

I could reproduce solutions, but I never understood them.

Years after I saw a bunch of good practicable examples and I just understood what the concept was about.

After this realization, I refined my learning approach.

1. Fly over the core concepts.

2. Try a bunch of examples until I understand why I would need the concept.

3. Read the core concept thoroughly to eliminate the edge cases that are missing in the naive examples.

Yeah, I don't know why this post is so either/or. Why not both? I like projects that have docs with core concepts in one section, examples in another. Or where the core concepts give working examples as code snippets.

All coding tutorials I’ve come across struggle with this. I couldn’t care less about some scripted video building a trivial piece of software, even if it’s pretty close to what I was going to build. The optimal coding tutorial in my eyes would just be a day in the life of a software engineer building something new and thinking out loud. Of course that wouldn’t do well in video format.

I think this is just the tech equivalent of teach a man to fish instead of yada yada.

So true, and this is a dilemma, right? People who build frameworks do so to make it easier for others to ship products. In the process of building the framework, they become better developers themselves. However, others now have to learn their abstractions, which distances them from the underlying concepts. This can make it harder for them to master the core skills needed to surpass the framework. I had that feeling when I learned Rails, only to realize it hid so much from me that I eventually had to drop it and try doing things from scratch.

Im quite good at writing pieces of code but if the application gets sufficently complex i tend to attack the problem by rewriting things in a circle. Sometimes complexity puts me in an infinite loop of rewrites. That this is an entirely different skill is quite the eye opener. Its now a known unknown if you like. Thanks!

Empathy is great but you need to understand cognition otherwise the empathy will be misplaced.

How is this code going to appear or show up for someone whose boss is breathing down their neck, or who is fixing a production problem at 2 am? You don’t know how valuable that answer is until you actually need the answer, and then you’ll pay a lot for it. If you can find someone who knows how to do it. Few people do.

I need both. Truly learning for me is learning core concepts, but examples are “known correct” cases I can test that understanding against. If something in the example is surprising, I know my model isn’t complete yet (or the example is wrong lol)

Yeah, it might be me. I learned microcontrollers by learning assembly, gdb, as, ld, then gradually switched to C, wrote my own "library", then slowly learned about vendor library and gradually replaced by code with proper approach.

Can't imagine learning this stuff from the vendor code examples. I wouldn't understand a thing.

This approach works for me, but only when documentation is extensive. When vendor suggests "copy this example and tinker with code until it works the way you want", this approach just throws me off and I absolutely lose any will to learn. Examples are very important, but not as starting point.

Maybe I'm dimmer than the average techie, but I need both. Much of my current job is frustrating because it's a big company and every new task I encounter is presented with only an example of how the previous person did it. Instead of, "This is what we're trying to achieve, this is how the thing works, this is how we do it," all that ever gets exposed to ICs is the "this is how we do it" part. This makes it impossible to reason about, adjust, and troubleshoot when even the slightest deviation is required. Yes, there is often SOME documentation tasks which are performed very often, but it's often outdated or incomplete. But it's not in a wiki, so not just anyone can updated at any time, there's a whole obnoxious process for updating the docs, which is why they never get updated.

Now that I think of it, this reminds me quite a bit of my time in the military...

I'm with you on this. My learning style is to read the reference manual cover to cover (metaphorically now). I can recall numerous instances of wanting to get into a new thing and finding the vast majority of recommended introductions to be the polar opposite of what I was looking for.

I'm going through this now as I decided to spend some time today learning the Drizzle ORM. The first things I found were all "here are half a dozen examples of queries", and I started getting frustrated: why are you using that syntax and not something else? What are the other options? I closed those and I'm much happier doing it my way: reading every page of the documentation before doing anything else.

I recently learned to ride with a stick, on a trip with my girlfriend and her dad. My gf just told me what to do, when to press the clutch and when to let go of it. This didn't help me at all; I didn't understand the nuances of what to do when, which things to do completely simultaneously and which to one just right after another. And then her dad chimed in, briefly explaining to me what the clutch actually does, and how does the connection between wheels and engine affect both of them. I instantly got it and didn't have to even hear instructions what to do in any particular situation. About 20 minutes later I was able to drive a car from a hand brake on a backwards slope, which is supposed to be one of the hardest things to do with a stick.

Understanding how something works from first principles is much more useful for some people, and I think that there's a lot of "some people" among the software engineers.

People are really consistent on needing both of those. And practice, and studying again after practice.

How much of those things they need varies from person to person, but they always need all of them.

This also stood out to me as obviously wrong in the article. Since time immemorial, we have taught math by teaching the core concepts and building on them incrementally. Since people do successfully learn how to do math, this directly disproves the author's claim that people don't learn that way.

This is something I'm starting to pick up and use from a mentoring and onboarding perspective. By now, I fairly openly wonder if someone needs conceptual or architectural clarification, technique on handling a thing, or a solution right there. And when we should have a follow-up call in the first two cases.

And having both thoughts and material available for a specific -> general, as well as a general -> specific path around is very good, because in more complex topics, it helps to be able to do both. Let them get a grip on some concrete things, then bring in the abstract ideas. Or let them learn the abstract concepts and show them how they can do concrete things with it.

I only started thriving in school once I started practicing theory construction in my head.

Hypothesis->test->refine

I’m not sure I could still do it in realtime today. It takes a lot of cycles to do this and reading or pausing videos to process is more my speed now.

I’ve ended up spot tutoring a lot of people who still don’t get it. Having a theory of the system lets you answer their questions where a classmate would not be able to because they’re barely past rote.

I need an example and an explanation of what problem is being solved.

Pages of dense text with lots of jargon, like a recent K8s course I've been doing are just something I find utterly useless for learning unless it involves a good amount of accompanying hands-on learning.

I wish that wasn't buried on page 733!

Or from Abelson (one of the SICP authors) similar, approximately:

Code should be written for humans to understand and only lastly for computers to understand.

"Programs are meant to be read by humans and only incidentally for computers to execute."

From the preface to the first edition of Structure and Interpretation of Computer Programs by Abelson & Sussman (which predated Code Complete by a decade).

It's a maxim I live by although my employers always seem to insist on the computers executing part for some reason.

Visual Basic in VS has aggressive autocomplete and it gets pretty annoying. You often want to write things in a different order and end up having to delete the auto-inserted endif/quotes/brackets/variable names (if it's not yet declared, it changes it to become something else that is), etc.

I agree about auto-complete, but already the editor Brief for MS-DOS, at least some 35 years ago, allowed you to define arbitrary templates for auto-completion.

For example, when writing a C program you could choose to have "f<TAB>" expanded to "for (=; <=; ++) {<LF><TAB>;<LF>}<LF>" or whatever indentation you preferred.

There are many modern programming editors that allow a similar customization, though unfortunately for many of them this requires a more complicated procedure than in the far past.

For any programming language with a verbose syntax, I consider necessary to take your time and define in your editor templates that would allow the fast writing of any program structure with a minimum number of key presses.

About the first item on your wishlist: If by "brackets" you mean {} (in C-like languages), there are IDEs that can be configured to create pairs of them every time you hit return after an expression that can take them. The downside (if you care) is that, if you wanted to write an if, while, or for with only one line, and therefore no scope delimiters, it will force you to create the scope anyway. You may not care.

If by "brackets", you mean [], to access an element of an array or vector or map or whatever, yes, it could do that as soon as you gave it the name of an array or vector or map or whatever. But then if you wanted to deal with the array or vector or map as a whole (which you want to do sometimes), the brackets have to go. I would estimate that 30% of the time I want to deal with the array as a whole, so such a feature would be annoying and in my way 1/3 of the time.

Terminators are a win more of the time. But when they're not, I meant to be continuing one line of code across two lines of file. If it auto-added a terminator (semicolon, say) at the end of the first line as it opened the second, I might not even notice until compile time. That would be highly annoying.

Public and private I don't want determined by a tool auto-determining the "most efficient" set. I want them determined by my sense of what the class is, and therefore what the public interface should be. Some of the things that are private are less efficient, but are private because they're implementation details and I don't want callers able to fiddle with them.

So, that's my whiny personal take on some things on your list. Maybe I've adapted myself to the existing tools. But I personally think that many of your items, if you implement them, you will find that you don't really like how they work out.

> You're editing a file (or parts of different files) and are focusing on say 5 methods that are interacting. I want to see all of them on the screen at the same time, without having to struggle to open and manage many windows with for example VS horizontal/vertical sliders.

I think that is, why editors like emacs and vi are really popular.

- Data conversion. So I created a HashSet for something but realize I need to change it to a Dictionary or a Tuple, just make it happen. If it requires brainwork then show me all the places that requires supervision where I have to say ok or make an edit myself.

How different would that be from changing the type and editing all the places the compiler complains about?

Actually it has gotten worse because our software abstractions have become a lot more complex.

Some of what you described, having 5 methods on screen, or finding all locations failing type checking, I have been using (neo)vim for successful over many years.

I load the output of the type checker (or compiler) into vim. I then have a list of locations to inspect. I can move between the locations. I can open multiple locations (same file or not) at once on the screen. Nowadays, Copilot assists in the refactoring besides the usual vim commands/regex/macro.

Opening 5 pane for 5 methods is similarly easy. I can also use a side panel to quickly view all methods and jump between them in addition to the traditional vim motions.

Language servers (LSP) of course makes the whole experience delightful. Jumping and navigating around the code etc.

All of that is keyboard driven, with many keyboard shortcuts personalized to my liking.

Here is an example of my workflow. I run the compile/typecheck command in a terminal, via a script that runs the command as soon as a source file has changed. It also saves the output into a file at a standard location. Saving in vim triggers the command to re-run. Then a key press reloads the output of the command to quickly jump around.

And navigating and modifying brackets is trivial in vim, especially with the right extension. Auto inserting brackets, I never found a plugin that I liked enough yet.

It's not all nor exactly what you asked for. But it's something.

I think the reason the text editor experience hasn't improved that much is because it's not often a bottleneck.

Thinking and learning are the hardest parts of programming. Typing faster doesn't help that much.

I may not be understanding you correctly, so please let me know if I've gotten it wrong.

Some of the stuff you're talking about -- like brackets and terminators -- make explicit the syntax and greatly improve tooling. Usually editors have features that can add these in or you. But in some cases something is obvious to you, but is really one valid choice among many and the tooling can't read your mind without something like a design doc to guide its decisions.

For others -- like whether to use a HashSet or Dictionary or Tuple -- those have performance implications and it's not always clear in the abstract when to use one or the other. But for explicit languages like Java (and I would assume C#) you should be able to refactor a method call to take a different type. Then you just have to change one method and refactor all the calls to it.

I've been experimenting with the pro Gemini and ChatGPT o1. They're both really bad at coding Python and JavaScript. They write buggy code and will often introduce bugs when attempting to fix another. Both feel like they're rushing to answer instead of thinking about the requirements. I'd say we're still a bit away from having tools that can "read your mind" or understand what matters to you and what doesn't the way you'd (or we'd) like them to.

Potentially even worse: consider the data we're training on. These tools will be adopting the thought patterns of the average coder since most code is produced by average and below average coders. Even if we trained the tools only on the highest quality code, it's not clear that most coders would know how to prompt it correctly. So I think if you've been coding for 10-20 years chances are decent that you'll always be a little disappointed with the tooling if you're expecting instant wizardry.

That said, non-AI static analysis tools have been great for a while and will get even better. Adding AI to them will improve them further. So I think you can have a great experience if you're thinking of the tools as helping you be an artist rather than as an artist you can give a spec to and get back a decent result.

EDIT: It might be fun to experiment with telling the AI what you want your editor to do more of and asking the AI to help you configure it. There's a lot of non-AI tooling in plugins. Getting an LLM to help you pick the right plugins for your lifestyle may be the best bang for your buck.

> You're editing a file (or parts of different files) and are focusing on say 5 methods that are interacting. I want to see all of them on the screen at the same time, without having to struggle to open and manage many windows with for example VS horizontal/vertical sliders

Regarding this, maybe haystack could be interesting for you

https://haystackeditor.com/

I haven't tried it myself, but I intend to.

Have you tried github copilot?

It's not doing multi-file editing yet, but once it does, I think it's pretty much what you are looking for.

> The whole concept of coding feels pretty much the same today as back then.

The whole concept of programming languages has not changed that much. We have the two big pillars that is the Turing Machine and Lambda Calculus (and various others) Everything after that has been abstractions, and when the abstractions are good, we call them paradigms. But it's all abstractions, and ultimately we are just writing instructions for a really dumb machine to compute data for us.

> Why do I need to worry about small language specifics like brackets, terminators and so on when tools should be able to auto-complete them for me?

Because the computer is something really simple, and the programming language is just a idea conduit from your mind. Those delimiters are as important as the language keywords, because they are part of the RULES. Auto-completing them will require more RULES and more delimiters.

> You're editing a file (or parts of different files) and are focusing on say 5 methods that are interacting. I want to see all of them on the screen at the same time

Vim and Emacs. Or Smalltalk IDEs like Pharo

> Data conversion

Vim and Emacs macros. But the truth is data encodings are very important, because for the computer, it's all bits, we assigned meanings to these bits and enacted RULES that describes how to manipulate them according to these meanings. Morphing from a set of RULES to another will require more RULES.

I will urge you to try a live programming environment (SLIME for Common Lisp, Pharo for Smalltalk, The web inspector for Javascript (not great)). It feels like working on a boat in the middle of the sea instead of having it on land imagining what it feels to sail it.

I think one of the main improvements we've - interestingly - been unable to widely adopt is an actual live programming environment. Smalltalk was this. Nowadays I mainly use Common Lisp for something reasonably close.

We're still mostly stuck in an edit->compile->test cycle. Stuff like TDD and debuggers help here, but considering the untapped potential for what programming environments could be, it seems to me like we're stuck on a local maximum.

Edit: Don't get me wrong, programming in Smalltalk didn't seem entirely pragmatic to me. Reproducibility becomes something you need to actively worry about, with popular tech stacks it's kinda built in. My point is the potential of such approaches, not the pragmatic viability of the implementations we've had so far.

When it comes to writing code being stuck in time, I'm expecting that LLMs replace programming languages rather than programmers. We aren't there yet and LLMs, or the next iteration of architecture, need to get better at logically working through and validating code, but I do think we'll get there.

When you think about it, its really pretty ridiculous that a programmer will ask an LLM to write code that the programmer can copy and ultimately compile into machine code for yet another computer to use. Cutting out the intermediary steps seems like a logical next step.

I feel the same, and I am happy that new programming languages like Go or Swift make small improvements.

I still feel I need a different programming language to write business code.

The problem isn't the IDE, but that we are still using a programming language 24 years old.

"Why do I need to worry about small language specifics like brackets, terminators and so on when tools should be able to auto-complete them for me?"

Actually, if you are using an IDE, there's probably a flag you can flip for that. It's a very common feature, to the point that I often find it in places I'm not expecting, like the web-based security training code platform my employer periodically pushes us through.

I'm not a fan, but some of it is just that my habits haven't developed around it.

There have been a number of tries at going even deeper, and trying to make it so the code is valid at all times. I suspect this one fails because we pass through more invalid states than people realize. For instance it's not uncommon for me to copy & paste some data from somewhere to embed into a program, and to massage it in my code editor until it is valid syntax, but it isn't "valid" until the very end. Smaller scale things like this happen all the time. It is more constricting than I think people generally realize to have to be valid every second.

"You're editing a file (or parts of different files) and are focusing on say 5 methods that are interacting. I want to see all of them on the screen at the same time, without having to struggle to open and manage many windows with for example VS horizontal/vertical sliders."

We've tried that already... and actually I'm with you, it's awesome. I suspect this is just because by the time you've got all the other IDE gizmos on the screen it's hard to do too much splitting. But my normal code setup is three emacs windows side-by-side on the screen (and, that is, windows, managed by the windowing system, not "frames" within emacs), each of which then can and often are further split once vertically. If I have to go all the way up to truly using 6 contexts at a time, something has probably gone wrong architecturally, but 2 is extremely common and bursts up to 3 and 4 a daily occurrence.

Watching some people recently trying to get into a largish code base, and watching them interact with it basically through a single window and at times not even with an IDE, really makes me think one of the larger problems is people learning how to "turn the lights on" in a code base. It isn't even a matter of implementing features at this point, honestly almost any environment already has a ton. You need to learn to use them.

"Data conversion. So I created a HashSet for something but realize I need to change it to a Dictionary or a Tuple, just make it happen."

We tried that already... and it comes with some substantial costs you may not realize.

First there's the obvious performance one. Make it easy to auto-convert them back and forth without any syntax fuss and you'll end up people writing loops in which the 1,000,000-million element hash table is converted both back and forth between a hash table and a tuple list in a loop, once per element, and you end up with the sort of bloated programs we all like to complain about. (Indeed, this sort of thing is one of the root causes, though far from the only one.)

The more subtle one is that automatic coercion, of which this is an example, is just generally a bad idea. The programmer ends up with a too-fuzzy idea of what is going on, and that fuzziness manifests not just in the aforementioned performance issue, but also, bugs, when it turns out that the properties of various structures being autoconverted back and forth are actually important to the code. The most common example which is increasingly widely regarded as a bad idea is "falsiness", where the language tries really hard to have a concept of true or false for all sorts of data structures, but the bugs that emerge from empty strings being read as false unexpectedly and such make this generally not worth it. In the case you cite, the data structures are not the same; they differ substantially in what they do with multiple values for a given key, and how order-sensitive they are, and in the world of programming, these details all matter. Especially because they end up being used to construct security systems.

It is hard to see the general sweep of programming language development, but in general at the moment I think languages are headed away from auto-conversion. What you can see is languages and libraries developing better "interface"-like abilities, where maybe they can declare that they just need this or that bit, and then you can pass multiple different structures in. See for instance __getitem__ in Python. This is a much better approach; there's still some fuzziness cost but the offsetting benefits are much stronger so it's a much better trade.

Haha selfless, or shameless!

I didn't find it contradictory. The first one is about how to start learning about something more easily and the second one about how to organize it all so that it's easier to use and understand as a whole. That may also help with getting started too.

I personally agree that examples are a very efficient way to get started and you can learn the details incrementally in a top-down fashion. Some text books during my studies took the bottom-up approach (even explicitly mentioned it) and I never quite liked it.

If the core concepts are simple and not too many, then it probably doesn't matter that much. The point is to get started easily.

I think he was referring to Kernighan when he said that.

Obfuscated C contest seems to be challenging your view. Or Brainfuck.

Intentional coding-trolling aside, if whatever is happening in the head of the original developer is muddled, the resulting code is likely to be confusing even for people who know computers from the inside out.

> We refer to all the objects in the room (or anywhere else) whether the baby understands them or not.

And that helps the baby enormously; I remember reading that the more words that infants hear, the more their brains develop.

But we still point to objects — or to pictures in a children's book, as I did the other day helping my wife babysit a neighbor's grandbaby — and say the words.