3 ms·

This affects more than just beginning programmers. Many best practices we teach programmers today help insiders manage a project but hinder understanding in new

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 10y ago
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 10y ago
  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-steps-to-better-code https://www.joelonsoftware.com/2000/08/09/the-joel-test-12-s...
  - Silhouette 10y ago
    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 10y ago
      "...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 http://akkartik.name/about, https://lobste.rs/c/rue8pf https://lobste.rs/c/rue8pf. Any comments most appreciated. (My email is in my profile.) Thanks for a fun chat!

Silhouette 10y ago

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 10y ago
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-steps-to-better-code https://www.joelonsoftware.com/2000/08/09/the-joel-test-12-s...
- Silhouette 10y ago
  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 10y ago
    "...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 http://akkartik.name/about, https://lobste.rs/c/rue8pf https://lobste.rs/c/rue8pf. Any comments most appreciated. (My email is in my profile.) Thanks for a fun chat!