[Silhouette]

My experience has been similar. A good coding style for teaching, when the reader doesn't yet recognise the building blocks of a language or their idiomatic usage, is often very different to a good coding style for professional use, when the reader can be assumed to understand the concepts and idioms already.

[akkartik]

This affects more than just beginning programmers. Many best practices we teach programmers today help insiders manage a project but hinder understanding in newcomers to the project (even if they're familiar with the language, libraries, etc.). In a strange new project straight-line code is usually easier to follow than lots of indirection and abstractions. Comments are of limited value because most comments explain local features, but fail to put them in a global context. Build systems that automate a lot of work in our specialized industrial-strength setup turn out to be brittle on someone's laptop when running for the first time.

[Silhouette]

You raise interesting points, though I don't think this one is obviously true:

In a strange new project straight-line code is usually easier to follow than lots of indirection and abstractions.

I would argue that indirection and abstraction can always be harmful to code readability if the amount of complexity they hide is less than the added complexity from using them. For example, if your abstractions are leaky and you use them to break a long algorithm down into a hierarchy of very short functions, a reader probably still often needs to look through the implementation to figure out what is really happening, but now they have to follow several levels of indirection to find that information.

I would also argue that if you choose levels of abstraction that really do hide a lot of complexity most of the time, this can be helpful for beginners learning a new system as well. For example, this can happen when the abstractions in question have intuitive meanings, such as representing real world objects or other recognisable concepts from the problem domain you're working with. It can also happen when the abstractions represent common patterns of behaviour in some reasonably clean and concise form, such as navigating a data structure in a particular way.

In short, while I agree with you that straight-line code can be clearer than lots of indirection and abstractions, I think that is often because of the poor choices of the latter rather than the experience level of the reader with that particular project. If they were very new, they'd have to learn what the key concepts and common patterns of behaviour were anyway, and once they do understand those ideas, good code using them should be easier to follow than code written using more primitive concepts.

[akkartik]

I agree with this phrasing! The extra context I'd add to your statements is that poor choices of abstraction are overwhelmingly more common than good ones, and that insiders learn to live with them. The combination of getting used to them and to having lots of reasons to maintain status quo (compatibility considerations, minimizing chances of merge conflicts, etc.) means that in practice their radar is often off when it comes to gauging the quality of an abstraction.

To create good abstractions, constantly look for opportunities to "hallway usability test" [1] them with newcomers.

[1] https://www.joelonsoftware.com/2000/08/09/the-joel-test-12-s...

[Silhouette]

The extra context I'd add to your statements is that poor choices of abstraction are overwhelmingly more common than good ones, and that insiders learn to live with them.

There's definitely a tendency for that to happen, I agree. If nothing else, we often don't know what good abstractions will look like yet in the early days of a project.

Even if we do, the most useful abstractions might change as the project evolves. Fortunately, the kinds of abstractions that tend to be most useful for hiding a lot of complexity also tend to be quite stable, in the sense that while they might be extended or generalised as the project develops, it is rarely necessary to severely break backward compatibility.

In an ideal world, we could definitely have more natural tools for things like refactoring, source control and diffs/merges, though, to lower the kinds of barriers you mentioned and promote willingness to refine the design and keep it clean as a project develops.

[akkartik]

"...the most useful abstractions might change as the project evolves...it is rarely necessary to severely break backward compatibility."

At this point I should just plug my current project: http://akkartik.name/about, https://lobste.rs/c/rue8pf. Any comments most appreciated. (My email is in my profile.) Thanks for a fun chat!

[Silhouette]

Since you asked, I'll post once more. :-)

I think you have interesting ideas and laudable goals. It's nice to see some promotion of good coding style that goes beyond basics like how to choose good names (which are also important, of course, but well covered by existing material). It's also nice to see some recognition that what may be good for working with code in the small may not always be good for working with code in the large, which I think is not as well understood as it could be in our industry, to our cost.

Curiously, while I agree with many of the goals and much of your analysis of the problems, my own search for solutions has gone in almost the opposite direction. I tend to emphasize good modular design and clearly specified interfaces more as a result and to rely on ad-hoc examples and test suites less. It's not that I have a problem with the latter or don't use them, just that I don't find them sufficiently general and unambiguous on their own. So instead, my own thinking has often been about how we might improve the way we define interfaces and then connect modules using them, including evolution and being able to migrate code using a module from one interface to another efficiently and reliably if and when that becomes useful.

It's fascinating, and perhaps a little scary, that despite being interested in similar areas and having reached some similar conclusions about problems that it would be helpful to solve, we can still look in such different places for those solutions. I suppose that's a sign of how "young" our understanding of how to build software still is and how much we still have to figure out. Perhaps your project will bring some of those answers, and I wish you luck with it.