1. 3

    Agree with the larger point, but have trouble imagining the first suggestion being maintainable – projects already have trouble keeping docs up to date and keeping feature nubs (which are likely tightly tied to other implementation details) around seems quite difficult.

    Also not sure the initiative would be there on the user side, given the article’s (accurate) statements around people mostly choosing to open up a codebase when they need it to do something it doesn’t already

    1. 1

      ..projects already have trouble keeping docs up to date and keeping feature nubs around seems quite difficult.

      It shouldn’t be hard to check for consistent feature nubs in CI. And really that’s all it takes. Python’s doctests have shown that it is possible for documentation to be kept up to date. The mainstream now finds updating code without tests to be unacceptable. Outdated documentation will hopefully soon get the same bar. Maybe it takes a little extra effort, just like it takes extra effort to write tests. But both yield dividends in the long term.

      not sure the initiative would be there on the user side, given the article’s (accurate) statements around people mostly choosing to open up a codebase when they need it to do something it doesn’t already

      OP doesn’t take a position on whether the desire people crack open a codebase for is small or large. I’ve certainly tried many times to navigate the code for open source projects like gcc, vim and firefox. I wasn’t expecting it to be easy. I would totally have accepted subgoals of understanding something over a few weeks.

      1. 3

        From my understanding feature nubs would need to be coupled to implementation and in a separate branch/commit/etc. Folks have a lot of trouble keeping functional patches up do date with master branch (e.g. a lot of the work neomutt has had to do). Asking a OSS team (whose code constitute most of the code one might read) to do so seems like it might be a pretty large burden on top maintaining a project.

        Well he may not talk about the number of people who want to read code (not positive I got what you’re saying there), but he does open with “Most programmers agree that we don’t read enough code”. Yes, but it is important to note that you are someone who cares about reading code (you hosted this article and write about this on your website). I think once you look at the subset of people who read code, then the subset of those who might do these excercises, and then the subset of those who would go on to contribute to the project, it may start to feel like a pretty high cost.

        1. 2

          There’s room for maneuver with the tooling. @smalina and I hack on a project written in a form of Literate Programming where every feature is in a separate file. Just one example of how it’s possible to reduce the management burden for such scaffolding. If we decide it’s useful we can solve these problems.

          Even with a separate branch, it should be useful even if it’s not up to date with master, right? Better than nothing? I think we make bigger compromises everyday with conventional workflows.

          I think once you look at the subset of people who read code, then the subset of those who might do these excercises, and then the subset of those who would go on to contribute to the project, it may start to feel like a pretty high cost.

          If you start with the premise that the goal is to combat personnel churn, it may well be worthwhile. Think of companies or open source projects as pipelines turning smart noobs into experts on their code.

          1. 2

            Paraphrasing myself, I’m much less sure of the solution than I am of the problem. I apologize that I’m about to address your points out-of-order but I think your second point is actually more general.

            On the topic of the subset of people who would actually go to the trouble to go through a project’s exercises, I’m as skeptical as you are that any of this will turn un-motivated people into avid code explorers. But that’s OK with me! If I can recommend things that actually make reading programs more pleasant for people like myself, akkartik, you, and many other Lobsters readers I suspect, that’s a huge win in my book.

            You make another good point that it’ll be hard to get maintainers to write exercises or “maps”. I agree that getting people to keep normal project docs up-to-date is hard already, and if I were arguing maintainers should just do more documenting and more explaining it would be a pipe dream (it may still be). However, what I may not have emphasized enough in the post is that I think it would be a net win if some projects did less module-level documenting in exchange for more high-level mapping and commit pointing. In other words, same amount of work just a different emphasis. Two other points about commit katas as I imagine them:

            1. One nice thing about a commit kata as opposed to a tutorial is that it can’t become stale. Having gone through a bunch of tutorials recently, I’ve been on the wrong end of stale instructions and they’re a huge motivation zapper and an annoying time sink for maintainers who have to deal with or write PRs to fix them.
            2. If you can really set up a way to host or point to multiple versions of a kata and people actually do it, you get a nice network effect where early kata contributors provide “free” help for later contributors.