11 ms·

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

464 points by imartin2k 2y ago

SilHunter 2y ago
[flagged]
- naavis 2y ago
  > psychopathic scammers like Robert Martin That is a pretty wild take. Would you like to elaborate on that?
  - zabzonk 2y ago
    have you read any of the arrant nonsense he comes out with?
    - deleted 2y ago
      [deleted]
    - tom_ 2y ago
      Right, but "psychopathic scammer" dials the criticism up a few notches, possibly to unreasonable levels - which i suspect is the point being made here. (That's certainly the point I'd have been making if I'd written the post you replied to.)
  - SilHunter 2y ago
    [flagged]
  - wiseowise 2y ago
    https://blog.wesleyac.com/posts/robert-martin https://blog.wesleyac.com/posts/robert-martin Part about politics, race, gender. He is insane.
mikkom 2y ago
Yeah bro but I read in twitter that I can just write "Code a health care app make it very profitable!" to AI and be billionaire!
auggierose 2y ago
A nice read, but I think there is a contradiction here that needs to be cleared up: 1) On one hand, the author says that humans learn from examples, not core concepts. 2) On the other hand, the author emphasises the importance of reducing "conceptual overload", by reducing the number of concepts while maintaining their expressiveness. So it is not that core concepts are not important for learning. Rather, it is essential to have a set of well-defined and well-documented core concepts which cover what the system can do. But of course, you also need plenty of insightful examples, and of course a "Getting Started" guide should start with examples, not core concepts. But if the core concepts are simple and few enough to fit into a "Getting Started", that's a win.
- kalaksi 2y ago
  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.
  - auggierose 2y ago
    There is even a headline saying "Getting started is the product". No, it is not. If your product doesn't have nice core concepts, then I don't even want to get started with it. Top-down is fine, as long as there is an actual bottom of core concepts.
    - ulbu 2y ago
      again, not contradictory. have good core concepts, combine with good entry corridors. good concept with entry blocked by obtusity and esoterics is not a product ready for consumption. i didn’t see the authors suggest that good concepts are unimportant.
WesSouza 2y ago
I thought this was going to be about genetics or something.
animal531 2y ago
Bit of a side issue for me: I was working on my Unity game the other day and thought to myself, have IDE's really not progressed all that much in the last 10-20 years? Default intellisense has definitely gotten a lot better, but apart from that and a few other minor things the whole concept of coding feels pretty much the same today as back then. The biggest positive change for me is outside of the editor, it has become easier thanks to much more access to libraries, documentation and just the sheer volume of user questions and answer sets we now have access to (and finally some new tools like ChatGPT that can aggregate those answers to on occasion deliver a reasonable answer). But overall the act of writing code seems to be stuck. As a result I'm currently taking some time out from my game to run some experiments. I don't want to create a new language, but instead I want to try and offload everything I can to the computer, let it do the drudge work while allowing me to create. Just 3 of the initial things I want to test: - 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? What about the private-public access chain (as well as other modifiers such as unsafe) when tools can auto-determine the most efficient set? - 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. - 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. In the case of Unity I also want to be able to click on a method and/or data set and tell it to convert it to a Burst Job with its accompanying NativeData sets.
- EnigmaFlare 2y ago
  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.
  - remoquete 2y ago
k2so 2y ago
Easier to use libraries over highly complicated (supposedly performant) have a significant advantage in driving more adoption. Recently I was trying to generate text embeddings from a huggingface model. Nvidia triton and text-embedding-inference (built by huggingface) were my two options. > why large companies are generally incapable of delivering great developer experience. I wanted to curl up and cry while trying to make nvidia-triton spit out embeddings . The error messages are cryptic and you need to have jedi like intuition to get it to work. I finally managed to get it work after like 2 days of wrangling with the extremely verbose and long-winded documentation (thanks in part to claude, helped me understand with better examples) Triton's documentation starts off with core-principles and throughout the entire documentation, they have hyper links to other badly written documentation to ensure you know the core concepts. The only reason I had endured this was because of the supposed performance gains triton promised but underdelivered (this highly likely being I had missed some config/core-concept and did get all the juice) On the other hand, text-embedding-inference has a two line front and centre command to pull the docker image and get running. The only delay was due to my internet speed before it started serving the embeddings. Then deploying this on our k8s infra was a breeze, minor modifications to the dockerfile and we are running. And on top, it's more performant than triton!
JimDabell 2y ago
On a side note, I have wondered if LLMs work more effectively with code that is well-structured and easy for humans to read than they do with spaghetti. Has anybody researched this?
mgaunard 2y ago
If humans understand how computers work, then you just have to write code for computers and can ignore the human element. Unfortunately the last few decades we decided that software engineers don't need to know how computers work anymore.
- inglor_cz 2y ago
  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.
  - wiseowise 2y ago
    > Obfuscated C contest seems to be challenging your view. Or Brainfuck. Both of those are leisure for experts.
jeroen 2y ago
As Spolsky said a long time ago: > It’s harder to read code than to write it.
- hinkley 2y ago
  I think he was referring to Kernighan when he said that.
deleted 2y ago
[deleted]
ants_everywhere 2y ago
My approach to dealing with lots of concepts is pretty much stolen from how babies learn language. Grownups talk around non-verbal babies as if they're not there. We refer to all the objects in the room (or anywhere else) whether the baby understands them or not. "How was your day at work?" "Oh it was okay, but traffic was bad so I didn't have time to get my usual coffee." Babies don't understand what traffic or coffee is, and they don't have to. They still eventually learn the language and really focus on the things that matter to them. At some point, a lot of us try to simplify by reducing the number of concepts we're exposed to, and we try to feel like we understand those fewer concepts. I've switched my approach to just being immersed in the way experts talk about the field, and just getting used to used to not really knowing what most things mean. It turns out you get a ton of information this way. Not only do you learn the vocabulary before you need it (reducing the time required later when you eventually need it) but also you pick up a sense of which things are fundamental (they come up a lot in conversation) and which things are extraneous detail (they're barely mentioned or only mentioned when something goes wrong).
- dctoedt 2y ago
  > 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.
austin-cheney 2y ago
There was an article similar to this less than 2 weeks ago: https://news.ycombinator.com/item?id=41566097 https://news.ycombinator.com/item?id=41566097 This whole issue of writing for people really distills down to two skills: 1. Empathy 2. Writing There is a world of difference between writing some code and writing an application, a product. That is all this article is about, though less explicitly. Empathy is a factor in this because its the difference between self-orientation and external-orientation. Self-orientated developers are primarily concerned with easiness, convenience, code vanity, and other subjectivity criteria. It comes down only to their effort of delivery. Externally-oriented developers are primarily concerned with architecture and documentation because for them success is all about how other people receive their work product. Simplicity is more important than easiness because externally-oriented developers know they cannot read minds and have no idea what other people find easy, but they do know how to reduce steps and keep their code small. In the brain writing an application, from a holistic product perspective, is no different than writing an essay, article, or book. Its all about organization and features. The code is something that comes later, like words on a page. For people who only write pieces of code they never develop the higher order organizational skills that brings it all together. It also works in the inverse in that if a person cannot write an essay with ease they cannot envision writing a new application. Those are the reasons I super detest frameworks. Frameworks deprive developers the practice necessary to write original software which means they are not developing those organizational skills. Its a massive gap that the inflicted cannot see, but is so enormously apparent to those that can see it. From a behavior perspective its no different than a learning or neurological disorder in that the inflicted know something is missing, but have no means to see what that something is, and that drives massive emotional insecurity.
- fsndz 2y ago
  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.
WillAdams 2y ago
Well, there is at least one effort at a solution: http://literateprogramming.com/ http://literateprogramming.com/ and I've found that John Ousterhout's recent book, _A Philosophy of Software Design_ is one of the most notable programming books of the past decade and speaks to many of these difficulties so well that I added it my effort at a list of (mostly) Literate Programming books: https://www.goodreads.com/review/list/21394355-william-adams?ref=nav_mybooks&shelf=literateprograms https://www.goodreads.com/review/list/21394355-william-adams... The other issue here is the still unanswered question: >What does an algorithm look like? and by extension, the further question of: How does one manage a visual representation of a program when it gets beyond the size of one screen/window, or a page in a book, or for the largest ones, a poster? With a bit of help of tex.stackexchange.com I was able to put together a Literate Programming system which allows me to use (La)TeX w/o the comment character which docstrip mandates: https://github.com/WillAdams/gcodepreview/blob/main/literati.sty https://github.com/WillAdams/gcodepreview/blob/main/literati... (it's a little clunky, since that file has to be customized for the files in a given project) but it allowed me to switch from having three files open in three different OpenPythonSCAD windows to a single .text file which makes a .pdf: https://github.com/WillAdams/gcodepreview/blob/main/gcodepreview.pdf https://github.com/WillAdams/gcodepreview/blob/main/gcodepre... which has a ToC, and multiple indices all nicely hyperlinked, and which makes a search/review of the code into a vertical scroll. That said, I sympathize w/ the author quite a bit, and often work up snippets of code using either Blockly or BlockSCAD3D: https://www.blockscad3d.com/editor/ https://www.blockscad3d.com/editor/ or https://github.com/derkork/openscad-graph-editor https://github.com/derkork/openscad-graph-editor https://raw.githubusercontent.com/WillAdams/gcodepreview/main/OSGE_cutjoinery.png?raw=true https://raw.githubusercontent.com/WillAdams/gcodepreview/mai...
ForOldHack 2y ago
Sacrafice nothing for clarity.
photonthug 2y ago
> “Humans learn from examples, not from “core concepts” Nitpicking maybe but I disagree with tfa on this point; not all humans work this way. Those of us who might actually prefer the general -> specific direction are already largely ignored in k12 and may only begin to thrive in higher education. Since we’re already kind of underserved, there’s no need to also deny that we exist!
- corytheboyd 2y ago
  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)
  - layer8 2y ago
    I also find “known incorrect” examples to be useful, for analogous reasons. But the worst is when there is no good and thorough description of the conceptual model and of how the concrete examples relate to it, because then the system remains a black box you can’t properly reason about, regardless of how many hands-on tutorials and cookbook examples you’ve seen.
  - rustyminnow 2y ago
    Yes! Both are valuable, and sometimes you need to iterate between and within each. Like if the conceptual components are mutually recursive (A is defined in terms of B, B in terms of A (SOLR anybody?)), skimming the docs can give you a "pencil sketch" level model, examples can flesh out the relationships between components, and re-visiting the docs with extra context can provide a more precise model.
- vbezhenar 2y ago
  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.
CharlieDigital 2y ago
From Code Complete: “The smaller part of the job of programming is writing a program so that the computer can read it; the larger part is writing it so that other humans can read it.” (P.733) Has stayed with me for ~20 years.
- dbalatero 2y ago
  I wish that wasn't buried on page 733!
  - CharlieDigital 2y ago
    The whole books has some good nuggets but it definitely makes you work for it :)
- zelphirkalt 2y ago
  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.
- pmg101 2y ago
  "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.
  - TeMPOraL 2y ago
    The computer executing part is the one that's both necessary and sufficient. The human reading part is neither. It's nice, important, and long-term indispensable - exactly the kind of thing economic pressures fight against.
    - michaelcampbell 2y ago
samatman 2y ago
The major part of this post is about documentation, and would have benefitted greatly from reference to the 4doc model: https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/ It's basically saying: don't just provide a reference, provide how-tos as well, and lead with them because they're the part of the total documentation which users generally want to see first. Generally, mind you, I tend to go straight to the reference material but not always. Not that 4doc is a silver bullet or a law of nature, Hillel Wayne has some good things to say about that here https://www.hillelwayne.com/post/problems-with-the-4doc-model/ https://www.hillelwayne.com/post/problems-with-the-4doc-mode...
Olshansky 2y ago
Selfless shill of a blog post I wrote & shared last week: Move Fast & Document Things [1] My goal wasn't to be philosophical but share actual tips on how our small team [2] enforces (not automated, not AI, but deep, hard reviews) a culture for writing code for ourselves and each other. All my personal friends who are engineering leaders at other orgs said "We do the same thing but you actually wrote it down". Would appreciate ↑ if it brought anyone value! [1] https://olshansky.substack.com/p/move-fast-and-document-things https://olshansky.substack.com/p/move-fast-and-document-thin... [2] https://github.com/pokt-network/poktroll/graphs/contributors https://github.com/pokt-network/poktroll/graphs/contributors
- pmg101 2y ago
  Haha selfless, or shameless!
powersnail 2y ago
People learn things differently. I really need the "core concept" first, before diving into examples, (unless the core concept is extremely simple). Many tutorials are like hand-holding Lego building. Here's your Lego pieces, watch me and follow me in building this toy project, and you'll know how to Lego at the end of the day. I just don't function very well in this model. I want to know how and why decisions are made. I want to see things from the author's perspective. I want to know how the Lego pieces each feels like, and how they connect to each other, and how you arrive at certain designs in a certain way. Trying to follow tutorials before at least some high-level, conceptual discussion, feels to me like I'm trying to reverse-engineer something that I shouldn't need to. Most of the time if I'm approaching a new library or framework, I read read the introduction texts, and skip the "Getting started" code samples. Usually, there's going to be some sort of "Advanced" section where a lot more talking and discussing of concepts happens, and that's what I'd like to dive into first. I'll go for the API references next, try to grasp what the important interfaces look like, and finally I'll get back to the basic code samples in the beginning of the tutorial.
- brugidou 2y ago
  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.
- rubslopes 2y ago
  I agree. Many coding courses start with setting up your environment, where to download the base packages... I much prefer the core concepts first.
- bbor 2y ago
  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!
bambax 2y ago
The title of the post is debatable, as code is only written for humans. Computers don't need "code", and especially not high level code. They're happy with machine instructions. We write code because machine instructions are much too hard for us to write, and even harder to read. We should not think of code as a way to interact with computers. Code is a way for us humans to formalize our thoughts so that they become so unambiguous that (even) a machine can follow them.
shahzaibmushtaq 2y ago
First you write code for computers, then you rewrite the same code for humans.
deleted 2y ago
[deleted]
Jtsummers 2y ago
Someone, a one day old account, wrote and then deleted this while I was writing a reply: > No other engineering discipline thinks this way. You design circuits for performance, manufacturing, and cost, not other engineers. Yeah, that's why we don't produce schematics, diagrams, and blueprints or maintain those things over the years. Software development is a design discipline, not a construction discipline. The analogs in engineering disciplines to source code are not the circuit, the car, or the bridge artifacts, but the schematics, diagrams, and models that go into their development. And yes, practitioners in engineering disciplines absolutely care about communicating with other people (including other engineers), that's a substantial portion of their job in fact.
bodeadly 2y ago
Writing code is easy. Knowing /what/ to write is hard. I know how to write English. But that doesn't mean I can write a book (that someone would want to read). AI can write code. But it still has to be told what to write.
osigurdson 2y ago
I've seen the aircraft / bullet heatmap diagram a few times. However, I'm always left wondering "was this a purely empirical analysis?". Clearly engineers would have some sense of what areas would bring an aircraft down (loss of engine, loss of tail strike me as obvious with no experience in aircraft design beyond paper planes). It is a great prop for survivorship bias of course!
osigurdson 2y ago
>> Humans learn from examples, not from “core concepts” So true. Humans are great at building mental models from raw data. Only after we learn our mental model is wrong we RTFM (unless your role is very specialized of course).
deleted 2y ago
[deleted]
nextworddev 2y ago
Yes basically that’s why learning AWS has a steep learning curve because the implementation details leak heavily to the API surface.
augustk 2y ago
Regarding the artwork of two ducks: https://www.pixsy.com/image-licensing/correctly-attribute-images https://www.pixsy.com/image-licensing/correctly-attribute-im...
throwaway14356 2y ago
The flood of feedback from power users shouldn't prevent a simple experience for a new user. The hard part is gradually exposing the new user to ever more complicated goodness in the correct order to upgrade them gradually.
luxuryballs 2y ago
it definitely helps if you design it to be easy for people before you start writing the code, that’s the primary goal of the project architecture design imo
teddyh 2y ago
To interpret the headline literally: Writing code for humans is actually relatively easy; it’s called “literature” (or “technical writing”). What’s hard is writing code (for computers) which is also easy for humans to understand. Anyone who has written polyglot code knows the enormity of the challenge, but also knows the tricks to make it work. I.e. you have to do a lot of things which means something to one “reader”, but is meaningless to the other, and vice versa. For example, variable names are meaningless to the computer, but very important to humans. And so on.
0xbadcafebee 2y ago
> Too many programming books and tutorials are like “let’s build a house starting from scratch, brick by brick” when what I want to “here is a functioning house, let’s learn about it by changing something and then seeing what happens” That's how I taught myself how to program. I spent years getting good at writing small, simple, kinda crappy programs. Later on I learned I wasn't eligible for better software development jobs, because I had absolutely no fundamental knowledge about software design, programming languages, and computers. It was humbling walking out of a job interview realizing how much I didn't know because I never learned the boring way. Always read the whole manual. Always learn the fundamentals.
jakobov 2y ago
Codeisforhumans.com
jbverschoor 2y ago
It’s not.
- deleted 2y ago
  [deleted]
rkagerer 2y ago
I write all of my code for humans. Whether that's me, or some other poor schmuck who'll have to figure out my intent years from now. I don't find code-writing hard. Reasoning comprehensively about your problem, collaborating with other stakeholders to discover and guide them along the best path, learning specialized skills (eg. new math or industry conventions), devising efficient algorithms, conveying your program's structure and patterns such that they're obvious and have elegant boundaries - that's the part that showcases talent. A lot of it comes down to communication and clarity.
known 2y ago
[dead]
082349872349872 2y ago
A view from 1985: https://pages.cs.wisc.edu/~remzi/Naur.pdf https://pages.cs.wisc.edu/~remzi/Naur.pdf [pedantically: the theory generated by a program and the theory generated by the axiomatisation in the heads of its programmers should be equivalent, but if you only have one it'll be easier to derive the former given the latter than the other way around]
fredgrott 2y ago
I kind have no comment as my favorite Song is by PinkFloyd where its encouraged to ignore teachers...
neuronet 2y ago
At the end the author wrote something without explanation that I found cryptic. It is something I am curious about as I am starting to work on a software package: Avoid “scaffolding” (code generation) I wasn't sure what this meant, so wanted to highlight it. I chatted with ChatGPT the following is an edited transcript of what we came up with. Note it is not a direct quote from GPT but highly edited cyborg quote from long conversation we had: The term "scaffolding" in software development refers to frameworks that automatically generate boilerplate code to quickly set up the structure of a project (think Django). This can include things like generating project directories, files, and initial code to get started with minimal manual setup. In the context of that article, the rule "Avoid scaffolding (code generation)" likely is implying that while scaffolding tools can be useful for quickly getting a project off the ground, they can generate generic or bloated code that can make the project harder to maintain and understand/read in the long run, with a steep learning curve. And *readability* is the point of the article. If your guiding values in writing a software package is producing easy-to-read, easy-to-learn, and easy-to-use code *for humans*, then avoid scaffolding. That last sentence is all me sorry. I have no idea if the author would agree with the above sentiment, but it seems pretty reasonable. Like most coding rules, there are reasonable exceptions. Opinionated is sometimes good, and the justification for it may scale with the complexity of the subject matter and the intended users and use case. E.g., how many different ways are there to achieve the goal(s) of your software, and do you want to enforce one particular way, given your intended user? If so, then depending on the specifics of the problem you are solving, you may need scaffolding. For instance, DeepLabCut (https://github.com/DeepLabCut/DeepLabCut https://github.com/DeepLabCut/DeepLabCut) is great software with tons of scaffolding. It is a machine vision framework written for experimentalists to track animal behavior, so boilerplate is great for them. The developers have put a ton of thought into how individual projects should be structured so the users who don't know anything about machine learning don't mess things up. Anyway, this is useful for me to think right now as I am building a new project so I'm curious what others think.
uknowWhoA 2y ago
[dead]

464 points by imartin2k 2y ago

SilHunter 2y ago

[flagged]

naavis 2y ago
> psychopathic scammers like Robert Martin That is a pretty wild take. Would you like to elaborate on that?
- zabzonk 2y ago
  have you read any of the arrant nonsense he comes out with?
  - deleted 2y ago
    [deleted]
  - tom_ 2y ago
    Right, but "psychopathic scammer" dials the criticism up a few notches, possibly to unreasonable levels - which i suspect is the point being made here. (That's certainly the point I'd have been making if I'd written the post you replied to.)
- SilHunter 2y ago
  [flagged]
- wiseowise 2y ago
  https://blog.wesleyac.com/posts/robert-martin https://blog.wesleyac.com/posts/robert-martin Part about politics, race, gender. He is insane.

mikkom 2y ago

Yeah bro but I read in twitter that I can just write "Code a health care app make it very profitable!" to AI and be billionaire!

auggierose 2y ago

A nice read, but I think there is a contradiction here that needs to be cleared up: 1) On one hand, the author says that humans learn from examples, not core concepts. 2) On the other hand, the author emphasises the importance of reducing "conceptual overload", by reducing the number of concepts while maintaining their expressiveness. So it is not that core concepts are not important for learning. Rather, it is essential to have a set of well-defined and well-documented core concepts which cover what the system can do. But of course, you also need plenty of insightful examples, and of course a "Getting Started" guide should start with examples, not core concepts. But if the core concepts are simple and few enough to fit into a "Getting Started", that's a win.

kalaksi 2y ago
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.
- auggierose 2y ago
  There is even a headline saying "Getting started is the product". No, it is not. If your product doesn't have nice core concepts, then I don't even want to get started with it. Top-down is fine, as long as there is an actual bottom of core concepts.
  - ulbu 2y ago
    again, not contradictory. have good core concepts, combine with good entry corridors. good concept with entry blocked by obtusity and esoterics is not a product ready for consumption. i didn’t see the authors suggest that good concepts are unimportant.

WesSouza 2y ago

I thought this was going to be about genetics or something.

animal531 2y ago

Bit of a side issue for me: I was working on my Unity game the other day and thought to myself, have IDE's really not progressed all that much in the last 10-20 years? Default intellisense has definitely gotten a lot better, but apart from that and a few other minor things the whole concept of coding feels pretty much the same today as back then. The biggest positive change for me is outside of the editor, it has become easier thanks to much more access to libraries, documentation and just the sheer volume of user questions and answer sets we now have access to (and finally some new tools like ChatGPT that can aggregate those answers to on occasion deliver a reasonable answer). But overall the act of writing code seems to be stuck. As a result I'm currently taking some time out from my game to run some experiments. I don't want to create a new language, but instead I want to try and offload everything I can to the computer, let it do the drudge work while allowing me to create. Just 3 of the initial things I want to test: - 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? What about the private-public access chain (as well as other modifiers such as unsafe) when tools can auto-determine the most efficient set? - 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. - 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. In the case of Unity I also want to be able to click on a method and/or data set and tell it to convert it to a Burst Job with its accompanying NativeData sets.

EnigmaFlare 2y ago
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.
- remoquete 2y ago

k2so 2y ago

Easier to use libraries over highly complicated (supposedly performant) have a significant advantage in driving more adoption. Recently I was trying to generate text embeddings from a huggingface model. Nvidia triton and text-embedding-inference (built by huggingface) were my two options. > why large companies are generally incapable of delivering great developer experience. I wanted to curl up and cry while trying to make nvidia-triton spit out embeddings . The error messages are cryptic and you need to have jedi like intuition to get it to work. I finally managed to get it work after like 2 days of wrangling with the extremely verbose and long-winded documentation (thanks in part to claude, helped me understand with better examples) Triton's documentation starts off with core-principles and throughout the entire documentation, they have hyper links to other badly written documentation to ensure you know the core concepts. The only reason I had endured this was because of the supposed performance gains triton promised but underdelivered (this highly likely being I had missed some config/core-concept and did get all the juice) On the other hand, text-embedding-inference has a two line front and centre command to pull the docker image and get running. The only delay was due to my internet speed before it started serving the embeddings. Then deploying this on our k8s infra was a breeze, minor modifications to the dockerfile and we are running. And on top, it's more performant than triton!

JimDabell 2y ago

On a side note, I have wondered if LLMs work more effectively with code that is well-structured and easy for humans to read than they do with spaghetti. Has anybody researched this?

mgaunard 2y ago

If humans understand how computers work, then you just have to write code for computers and can ignore the human element. Unfortunately the last few decades we decided that software engineers don't need to know how computers work anymore.

inglor_cz 2y ago
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.
- wiseowise 2y ago
  > Obfuscated C contest seems to be challenging your view. Or Brainfuck. Both of those are leisure for experts.

jeroen 2y ago

As Spolsky said a long time ago: > It’s harder to read code than to write it.

hinkley 2y ago
I think he was referring to Kernighan when he said that.

deleted 2y ago

[deleted]

ants_everywhere 2y ago

My approach to dealing with lots of concepts is pretty much stolen from how babies learn language. Grownups talk around non-verbal babies as if they're not there. We refer to all the objects in the room (or anywhere else) whether the baby understands them or not. "How was your day at work?" "Oh it was okay, but traffic was bad so I didn't have time to get my usual coffee." Babies don't understand what traffic or coffee is, and they don't have to. They still eventually learn the language and really focus on the things that matter to them. At some point, a lot of us try to simplify by reducing the number of concepts we're exposed to, and we try to feel like we understand those fewer concepts. I've switched my approach to just being immersed in the way experts talk about the field, and just getting used to used to not really knowing what most things mean. It turns out you get a ton of information this way. Not only do you learn the vocabulary before you need it (reducing the time required later when you eventually need it) but also you pick up a sense of which things are fundamental (they come up a lot in conversation) and which things are extraneous detail (they're barely mentioned or only mentioned when something goes wrong).

dctoedt 2y ago
> 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.

austin-cheney 2y ago

There was an article similar to this less than 2 weeks ago: https://news.ycombinator.com/item?id=41566097 https://news.ycombinator.com/item?id=41566097 This whole issue of writing for people really distills down to two skills: 1. Empathy 2. Writing There is a world of difference between writing some code and writing an application, a product. That is all this article is about, though less explicitly. Empathy is a factor in this because its the difference between self-orientation and external-orientation. Self-orientated developers are primarily concerned with easiness, convenience, code vanity, and other subjectivity criteria. It comes down only to their effort of delivery. Externally-oriented developers are primarily concerned with architecture and documentation because for them success is all about how other people receive their work product. Simplicity is more important than easiness because externally-oriented developers know they cannot read minds and have no idea what other people find easy, but they do know how to reduce steps and keep their code small. In the brain writing an application, from a holistic product perspective, is no different than writing an essay, article, or book. Its all about organization and features. The code is something that comes later, like words on a page. For people who only write pieces of code they never develop the higher order organizational skills that brings it all together. It also works in the inverse in that if a person cannot write an essay with ease they cannot envision writing a new application. Those are the reasons I super detest frameworks. Frameworks deprive developers the practice necessary to write original software which means they are not developing those organizational skills. Its a massive gap that the inflicted cannot see, but is so enormously apparent to those that can see it. From a behavior perspective its no different than a learning or neurological disorder in that the inflicted know something is missing, but have no means to see what that something is, and that drives massive emotional insecurity.

fsndz 2y ago
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.

WillAdams 2y ago

Well, there is at least one effort at a solution: http://literateprogramming.com/ http://literateprogramming.com/ and I've found that John Ousterhout's recent book, _A Philosophy of Software Design_ is one of the most notable programming books of the past decade and speaks to many of these difficulties so well that I added it my effort at a list of (mostly) Literate Programming books: https://www.goodreads.com/review/list/21394355-william-adams?ref=nav_mybooks&shelf=literateprograms https://www.goodreads.com/review/list/21394355-william-adams... The other issue here is the still unanswered question: >What does an algorithm look like? and by extension, the further question of: How does one manage a visual representation of a program when it gets beyond the size of one screen/window, or a page in a book, or for the largest ones, a poster? With a bit of help of tex.stackexchange.com I was able to put together a Literate Programming system which allows me to use (La)TeX w/o the comment character which docstrip mandates: https://github.com/WillAdams/gcodepreview/blob/main/literati.sty https://github.com/WillAdams/gcodepreview/blob/main/literati... (it's a little clunky, since that file has to be customized for the files in a given project) but it allowed me to switch from having three files open in three different OpenPythonSCAD windows to a single .text file which makes a .pdf: https://github.com/WillAdams/gcodepreview/blob/main/gcodepreview.pdf https://github.com/WillAdams/gcodepreview/blob/main/gcodepre... which has a ToC, and multiple indices all nicely hyperlinked, and which makes a search/review of the code into a vertical scroll. That said, I sympathize w/ the author quite a bit, and often work up snippets of code using either Blockly or BlockSCAD3D: https://www.blockscad3d.com/editor/ https://www.blockscad3d.com/editor/ or https://github.com/derkork/openscad-graph-editor https://github.com/derkork/openscad-graph-editor https://raw.githubusercontent.com/WillAdams/gcodepreview/main/OSGE_cutjoinery.png?raw=true https://raw.githubusercontent.com/WillAdams/gcodepreview/mai...

ForOldHack 2y ago

Sacrafice nothing for clarity.

photonthug 2y ago

> “Humans learn from examples, not from “core concepts” Nitpicking maybe but I disagree with tfa on this point; not all humans work this way. Those of us who might actually prefer the general -> specific direction are already largely ignored in k12 and may only begin to thrive in higher education. Since we’re already kind of underserved, there’s no need to also deny that we exist!

corytheboyd 2y ago
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)
- layer8 2y ago
  I also find “known incorrect” examples to be useful, for analogous reasons. But the worst is when there is no good and thorough description of the conceptual model and of how the concrete examples relate to it, because then the system remains a black box you can’t properly reason about, regardless of how many hands-on tutorials and cookbook examples you’ve seen.
- rustyminnow 2y ago
  Yes! Both are valuable, and sometimes you need to iterate between and within each. Like if the conceptual components are mutually recursive (A is defined in terms of B, B in terms of A (SOLR anybody?)), skimming the docs can give you a "pencil sketch" level model, examples can flesh out the relationships between components, and re-visiting the docs with extra context can provide a more precise model.
vbezhenar 2y ago
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.

CharlieDigital 2y ago

From Code Complete: “The smaller part of the job of programming is writing a program so that the computer can read it; the larger part is writing it so that other humans can read it.” (P.733) Has stayed with me for ~20 years.

dbalatero 2y ago
I wish that wasn't buried on page 733!
- CharlieDigital 2y ago
  The whole books has some good nuggets but it definitely makes you work for it :)
zelphirkalt 2y ago
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.
pmg101 2y ago
"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.
- TeMPOraL 2y ago
  The computer executing part is the one that's both necessary and sufficient. The human reading part is neither. It's nice, important, and long-term indispensable - exactly the kind of thing economic pressures fight against.
  - michaelcampbell 2y ago

samatman 2y ago

The major part of this post is about documentation, and would have benefitted greatly from reference to the 4doc model: https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/ It's basically saying: don't just provide a reference, provide how-tos as well, and lead with them because they're the part of the total documentation which users generally want to see first. Generally, mind you, I tend to go straight to the reference material but not always. Not that 4doc is a silver bullet or a law of nature, Hillel Wayne has some good things to say about that here https://www.hillelwayne.com/post/problems-with-the-4doc-model/ https://www.hillelwayne.com/post/problems-with-the-4doc-mode...

Olshansky 2y ago

Selfless shill of a blog post I wrote & shared last week: Move Fast & Document Things [1] My goal wasn't to be philosophical but share actual tips on how our small team [2] enforces (not automated, not AI, but deep, hard reviews) a culture for writing code for ourselves and each other. All my personal friends who are engineering leaders at other orgs said "We do the same thing but you actually wrote it down". Would appreciate ↑ if it brought anyone value! [1] https://olshansky.substack.com/p/move-fast-and-document-things https://olshansky.substack.com/p/move-fast-and-document-thin... [2] https://github.com/pokt-network/poktroll/graphs/contributors https://github.com/pokt-network/poktroll/graphs/contributors

pmg101 2y ago
Haha selfless, or shameless!

powersnail 2y ago

People learn things differently. I really need the "core concept" first, before diving into examples, (unless the core concept is extremely simple). Many tutorials are like hand-holding Lego building. Here's your Lego pieces, watch me and follow me in building this toy project, and you'll know how to Lego at the end of the day. I just don't function very well in this model. I want to know how and why decisions are made. I want to see things from the author's perspective. I want to know how the Lego pieces each feels like, and how they connect to each other, and how you arrive at certain designs in a certain way. Trying to follow tutorials before at least some high-level, conceptual discussion, feels to me like I'm trying to reverse-engineer something that I shouldn't need to. Most of the time if I'm approaching a new library or framework, I read read the introduction texts, and skip the "Getting started" code samples. Usually, there's going to be some sort of "Advanced" section where a lot more talking and discussing of concepts happens, and that's what I'd like to dive into first. I'll go for the API references next, try to grasp what the important interfaces look like, and finally I'll get back to the basic code samples in the beginning of the tutorial.

brugidou 2y ago
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.
rubslopes 2y ago
I agree. Many coding courses start with setting up your environment, where to download the base packages... I much prefer the core concepts first.
bbor 2y ago
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!

bambax 2y ago

The title of the post is debatable, as code is only written for humans. Computers don't need "code", and especially not high level code. They're happy with machine instructions. We write code because machine instructions are much too hard for us to write, and even harder to read. We should not think of code as a way to interact with computers. Code is a way for us humans to formalize our thoughts so that they become so unambiguous that (even) a machine can follow them.

shahzaibmushtaq 2y ago

First you write code for computers, then you rewrite the same code for humans.

deleted 2y ago

[deleted]

Jtsummers 2y ago

Someone, a one day old account, wrote and then deleted this while I was writing a reply: > No other engineering discipline thinks this way. You design circuits for performance, manufacturing, and cost, not other engineers. Yeah, that's why we don't produce schematics, diagrams, and blueprints or maintain those things over the years. Software development is a design discipline, not a construction discipline. The analogs in engineering disciplines to source code are not the circuit, the car, or the bridge artifacts, but the schematics, diagrams, and models that go into their development. And yes, practitioners in engineering disciplines absolutely care about communicating with other people (including other engineers), that's a substantial portion of their job in fact.

bodeadly 2y ago

Writing code is easy. Knowing /what/ to write is hard. I know how to write English. But that doesn't mean I can write a book (that someone would want to read). AI can write code. But it still has to be told what to write.

osigurdson 2y ago

I've seen the aircraft / bullet heatmap diagram a few times. However, I'm always left wondering "was this a purely empirical analysis?". Clearly engineers would have some sense of what areas would bring an aircraft down (loss of engine, loss of tail strike me as obvious with no experience in aircraft design beyond paper planes). It is a great prop for survivorship bias of course!

osigurdson 2y ago

>> Humans learn from examples, not from “core concepts” So true. Humans are great at building mental models from raw data. Only after we learn our mental model is wrong we RTFM (unless your role is very specialized of course).

deleted 2y ago

[deleted]

nextworddev 2y ago

Yes basically that’s why learning AWS has a steep learning curve because the implementation details leak heavily to the API surface.

augustk 2y ago

Regarding the artwork of two ducks: https://www.pixsy.com/image-licensing/correctly-attribute-images https://www.pixsy.com/image-licensing/correctly-attribute-im...

throwaway14356 2y ago

The flood of feedback from power users shouldn't prevent a simple experience for a new user. The hard part is gradually exposing the new user to ever more complicated goodness in the correct order to upgrade them gradually.

luxuryballs 2y ago

it definitely helps if you design it to be easy for people before you start writing the code, that’s the primary goal of the project architecture design imo

teddyh 2y ago

To interpret the headline literally: Writing code for humans is actually relatively easy; it’s called “literature” (or “technical writing”). What’s hard is writing code (for computers) which is also easy for humans to understand. Anyone who has written polyglot code knows the enormity of the challenge, but also knows the tricks to make it work. I.e. you have to do a lot of things which means something to one “reader”, but is meaningless to the other, and vice versa. For example, variable names are meaningless to the computer, but very important to humans. And so on.

0xbadcafebee 2y ago

> Too many programming books and tutorials are like “let’s build a house starting from scratch, brick by brick” when what I want to “here is a functioning house, let’s learn about it by changing something and then seeing what happens” That's how I taught myself how to program. I spent years getting good at writing small, simple, kinda crappy programs. Later on I learned I wasn't eligible for better software development jobs, because I had absolutely no fundamental knowledge about software design, programming languages, and computers. It was humbling walking out of a job interview realizing how much I didn't know because I never learned the boring way. Always read the whole manual. Always learn the fundamentals.

jakobov 2y ago

Codeisforhumans.com

jbverschoor 2y ago

It’s not.

deleted 2y ago
[deleted]

rkagerer 2y ago

I write all of my code for humans. Whether that's me, or some other poor schmuck who'll have to figure out my intent years from now. I don't find code-writing hard. Reasoning comprehensively about your problem, collaborating with other stakeholders to discover and guide them along the best path, learning specialized skills (eg. new math or industry conventions), devising efficient algorithms, conveying your program's structure and patterns such that they're obvious and have elegant boundaries - that's the part that showcases talent. A lot of it comes down to communication and clarity.

known 2y ago

[dead]

082349872349872 2y ago

A view from 1985: https://pages.cs.wisc.edu/~remzi/Naur.pdf https://pages.cs.wisc.edu/~remzi/Naur.pdf [pedantically: the theory generated by a program and the theory generated by the axiomatisation in the heads of its programmers should be equivalent, but if you only have one it'll be easier to derive the former given the latter than the other way around]

fredgrott 2y ago

I kind have no comment as my favorite Song is by PinkFloyd where its encouraged to ignore teachers...

neuronet 2y ago

At the end the author wrote something without explanation that I found cryptic. It is something I am curious about as I am starting to work on a software package: Avoid “scaffolding” (code generation) I wasn't sure what this meant, so wanted to highlight it. I chatted with ChatGPT the following is an edited transcript of what we came up with. Note it is not a direct quote from GPT but highly edited cyborg quote from long conversation we had: The term "scaffolding" in software development refers to frameworks that automatically generate boilerplate code to quickly set up the structure of a project (think Django). This can include things like generating project directories, files, and initial code to get started with minimal manual setup. In the context of that article, the rule "Avoid scaffolding (code generation)" likely is implying that while scaffolding tools can be useful for quickly getting a project off the ground, they can generate generic or bloated code that can make the project harder to maintain and understand/read in the long run, with a steep learning curve. And *readability* is the point of the article. If your guiding values in writing a software package is producing easy-to-read, easy-to-learn, and easy-to-use code *for humans*, then avoid scaffolding. That last sentence is all me sorry. I have no idea if the author would agree with the above sentiment, but it seems pretty reasonable. Like most coding rules, there are reasonable exceptions. Opinionated is sometimes good, and the justification for it may scale with the complexity of the subject matter and the intended users and use case. E.g., how many different ways are there to achieve the goal(s) of your software, and do you want to enforce one particular way, given your intended user? If so, then depending on the specifics of the problem you are solving, you may need scaffolding. For instance, DeepLabCut (https://github.com/DeepLabCut/DeepLabCut https://github.com/DeepLabCut/DeepLabCut) is great software with tons of scaffolding. It is a machine vision framework written for experimentalists to track animal behavior, so boilerplate is great for them. The developers have put a ton of thought into how individual projects should be structured so the users who don't know anything about machine learning don't mess things up. Anyway, this is useful for me to think right now as I am building a new project so I'm curious what others think.

uknowWhoA 2y ago

[dead]