Peter Naur's view of programming • Hacker News Board

Re: Peter Naur's view of programming

#61

Post by aeldidi » Thu, Feb 04, 2021, 6:44 PM UTC

Rather than "Source Code is Worthless", I find it makes more sense to think of the lesson learned here as "Source Code is Only Worth Something to the Public if it's Well Documented and Stable", which happens to be true more often in practice.

For example, someone I used to know would always say that while the Linux kernel as a product (a free and open source operating system) is priceless, the source itself is worthless unless you have an understanding of its internals, and I think that this is generally true for codebases of similar size and complexity, although I'd argue Linux specifically doesn't fall into this area only because of the fact that drivers make up most of the code in it.

Stability is especially important when considering long term worth of code. When youtube-dl was removed from GitHub not too long ago, people were worried that the project would stop being updated and maintained, despite the fact that mirrors of the source code were everywhere. In that case, because the project needs constant updating and maintaining to keep up with websites like YouTube who have no incentive to continue to keep a stable API for downloading videos.

Re: Peter Naur's view of programming

#62

Post by rorykoehler » Thu, Feb 04, 2021, 6:45 PM UTC

chubot wrote: post #48

rorykoehler wrote: post #40

Earlier quoted context omitted.

Remote work should help you in this case. Writing and reading are scalable. 1:1’s are not for explaining how stuff works and why. If you don’t write this all down then you are introducing risk and key person dependency.

It depends on the situation. Documentation and in-person meetings aren't mutually exclusive. A meeting to go through the docs and update them is often very useful. Not everything has to be "scalable". There are many parts of the code that only 1 or 3 people will ever work on. In fact in most places I'd say that's most of the code.

I’ve never been unhappy when provided with thorough documentation.

Re: Peter Naur's view of programming

#63

Post by solatic » Thu, Feb 04, 2021, 6:46 PM UTC

rorykoehler wrote: post #40

QuercusMax wrote: post #29

The point about theory-building requiring (or at least being accelerated by) interpersonal communication / teaching rings very true. In the middle of last year, my team went through a major re-org, and I'm now working with a whole bunch of new teammates. My project didn't get cancelled in the reorg; in fact, it's actually come to more prominence due to synergy in the projects we work on. Essentially my new teammates…

Remote work should help you in this case. Writing and reading are scalable. 1:1’s are not for explaining how stuff works and why. If you don’t write this all down then you are introducing risk and key person dependency.

Reading and writing scale in theory. They require an organization staffed with people who are strong readers and writers. Unfortunately, many people, especially those forced into remote work during the pandemic, are not. They will not read through explicit, clear, but long documentation; they will not respond by writing questions of their own, and will often fail at writing explicit and clear documentation of their own.

You are who you hire.

Re: Peter Naur's view of programming

#64

Post by superjan » Thu, Feb 04, 2021, 6:49 PM UTC

This is easier to reason about if it’s not about your own code. Consider this: would you swap your own codebase for your competitor’s if you had the chance? For me, it’s a resounding no. I bet it’s the same from their perspective.

Re: Peter Naur's view of programming

#65

Post by jhallenworld » Thu, Feb 04, 2021, 6:52 PM UTC

Source code is most valuable to the person who wrote it / knows it intimately. If I can use my code on different jobs it will definitely save me time. For this reason I try to make any library code MIT licensed. This allows me to use it for different clients without them complaining. Our contracts are set up to allow this.

Often the customer's proprietary code is a small fraction of all the code.

Re: Peter Naur's view of programming

#66

Post by closeparen » Thu, Feb 04, 2021, 6:58 PM UTC

rorykoehler wrote: post #40

QuercusMax wrote: post #29

The point about theory-building requiring (or at least being accelerated by) interpersonal communication / teaching rings very true. In the middle of last year, my team went through a major re-org, and I'm now working with a whole bunch of new teammates. My project didn't get cancelled in the reorg; in fact, it's actually come to more prominence due to synergy in the projects we work on. Essentially my new teammates…

Remote work should help you in this case. Writing and reading are scalable. 1:1’s are not for explaining how stuff works and why. If you don’t write this all down then you are introducing risk and key person dependency.

It's not a one-way transfer of information.

- The student has questions that it wouldn't have occurred to the teacher to answer.

- The student gets confused and asks for things to be rephrased or reframed.

- The student has questions that don't currently have static answers, but get computed by the teacher in real time, according to an intuition and assimilation of the facts that the student is only beginning to develop.

- The teacher's answers are up to date, whether or not he has actually exercised the diligence to maintain the textbook.

- The teacher fields the questions that the specific students ramping on the project actually have, rather than trying to anticipate all possible questions of all hypothetical students (and still failing).

There is a reason we have college and not just reading lists. And those are subjects where the economics support massive investments in discovering the best / most broadly useful ways to present the ideas. The average software project isn't that.

The commoditized software factory is an MBA fantasy. The expertise held by "key persons" is a software team's greatest asset.

Re: Peter Naur's view of programming

#67

Post by blindm » Thu, Feb 04, 2021, 6:59 PM UTC

> Communicating the mapping of the code and the real world, as Naur describes, would have required us to document all these processes in meticulous detail. If we had tried to, I believe the result would’ve been multiple hundred pages describing the business processes

Or in other words: building in business logic is paramount and the only thing you should be doing if running a startup, otherwise these engineers are just dossing around with code that doesn't yield a profit.

Re: Peter Naur's view of programming

#68

Post by QuercusMax » Thu, Feb 04, 2021, 7:01 PM UTC

rorykoehler wrote: post #40

QuercusMax wrote: post #29

The point about theory-building requiring (or at least being accelerated by) interpersonal communication / teaching rings very true. In the middle of last year, my team went through a major re-org, and I'm now working with a whole bunch of new teammates. My project didn't get cancelled in the reorg; in fact, it's actually come to more prominence due to synergy in the projects we work on. Essentially my new teammates…

Remote work should help you in this case. Writing and reading are scalable. 1:1’s are not for explaining how stuff works and why. If you don’t write this all down then you are introducing risk and key person dependency.

Unfortunately for me, I started developing really bad RSI around January of last year, and typing has been incredibly painful. In the past I would have discussed things using whiteboards, sitting down side-by-side with code, etc.; these are all very hard to do if typing causes pain.

Interactive sessions are also very helpful, as there are so many assumptions and background material baked into things that often take a long time to unwind. Being able to gauge on-the-fly if the audience understands can save tons of time and confusion.

I've got 17 years of domain experience across 3 companies in the industry; there's no way I'm going to write all that down in my docs.

Re: Peter Naur's view of programming

#69

Post by dbrueck » Thu, Feb 04, 2021, 7:08 PM UTC

The article is great, though a more accurate (but admittedly less thrilling) title would have been "Poorly Documented Source Code Is Virtually Worthless".

Good source code includes level of intent comments, it explains the reasoning behind decisions (especially the tradeoffs that were made) and warns future readers of potential pitfalls.

In both a professional setting as well as when wanting to contribute to a favorite OSS project, few things are more frustrating than jumping into the code only to realize it's missing this type of info.

Re: Peter Naur's view of programming

#70

Post by ilaksh » Thu, Feb 04, 2021, 7:13 PM UTC

rorykoehler wrote: post #40

QuercusMax wrote: post #29

The point about theory-building requiring (or at least being accelerated by) interpersonal communication / teaching rings very true. In the middle of last year, my team went through a major re-org, and I'm now working with a whole bunch of new teammates. My project didn't get cancelled in the reorg; in fact, it's actually come to more prominence due to synergy in the projects we work on. Essentially my new teammates…

Remote work should help you in this case. Writing and reading are scalable. 1:1’s are not for explaining how stuff works and why. If you don’t write this all down then you are introducing risk and key person dependency.

I think it should help in a way. But I also believe that people overestimate how well one can learn in depth about a complex problem from reading or any mainly passive activity alone.

I know there is this theory about learning styles but it's largely debunked.

To get a really solid understanding of a topic such as a business domain and it's interaction with a complex process and application, it takes a certain amount of time and contact with real problems. The only time that people can quickly pick up new ideas from reading is when they have mastered all of the underlying concepts of that knowledge. But applications generally have layers of very specific knowledge required to understand the problem and existing solution.

The point of the article I think is that it's usually going to take a significant amount of time for new developers to become familiar, regardless of how good the source or documentation is.