What's opaque about "write everything down, including your assumptions and what you are going to try before you try it, write it out in full, and don't worry too much about it being in a neat structure because it's more of a scratch-pad"?

His main point is that we focus too much on the software tools, and not enough on how we think about the software we are modifying.

I can say from experience that writing things out on paper without looking at the code works, and more people should do it. Like he states in the slide-deck: it lets you off-load mental burdens, and avoid the problem of forgetting the details of a complex problem in the process of being unravelled. It lets you get back into the work weeks or months later.

Writing messy pseudo-blog-posts in github issues and very long code comments is how I kept my sanity on a project where I was the sole programmer for two years.

I've always found abstraction to be a double edged sword when trying to understand codebases. Sometimes it helps define the intent, but other times I'm going "WTF is this thing for real?" and tracking the abstractions through several files.

My favorite is tracking down a member function and being completely confused until I realize that I missed one of the layers and it was overridden in that instantiation.

I generally find that abstraction is good, but layering is bad. Let's say I have components A, B, and C that all do something useful and are good abstractions, the difference between good code and bade code is how they interact. In bad code A will call B and B will call C, from the top level it's completely opaque how everything fits together. I'd much rather A returns something and let's the caller pass it to B. There is very little difference in code required but it makes a world of difference to making it comprehensible.

IMO the most important thing when introducing a layer of abstraction is the name of the new component. I sometimes spend 2 or more minutes making up a name that best describes what this layer is about.

ProTip: Manager or Controller is not a good name. To me a good name is eg „PostDetailSerializerResolver“ - it’s a component that will resolve serializers for post detail objects. And according to concept of single responsibility, it should only do that. If you need it to do more, you must change the name.

> I sometimes spend 2 or more minutes making up a name that best describes what this layer is about.

Some of the best refactoring I ever did for long-term code-maintenance was nothing more than untangling a web of abstraction layers and renaming them to fit the actual context, changing nothing to the functionality of the code.

Sometimes you start out with an idea for what the architecture will be, but then things change and the naming isn't updated.

We tend to speak of abstractions in only positive terms. Some negative ones could include opaque, obtuse, disjointed, etc.

When I think of abstractions I think abstraction == API and good API design is very hard.

> ..it's worth thinking about how the particular abstraction mechanisms used in software impact a new contributor's productivity, vs. the productivity of someone more familiar with the codebase, especially for projects that are developed in the open, or with high developer turnover.

Oh yes. I work on this[1], and require very little inducement to talk about it[2].

[1] http://akkartik.name/about

[2] For example: https://news.ycombinator.com/item?id=13565743#13570092