3 ms·

So, one aspect of this post is: a) a lot of prior work has assumed that "comprehension" and "reading" are the same and b) reading is a bad approach to understan

by abeppu 6y ago

So, one aspect of this post is: a) a lot of prior work has assumed that "comprehension" and "reading" are the same and b) reading is a bad approach to understanding code. For me, this also calls to mind an old blog post from Peter Seibel about a disconnect where many of us think that we should all be reading code for our own understanding, somewhat like literature, but very few of us do and it rarely yields much. And one of the reasons why it seems that style of reading is ineffective, is that coming to an understanding of code is more like a scientific investigation than just reading prose. http://www.gigamonkeys.com/code-reading/ http://www.gigamonkeys.com/code-reading/ I agree with that point. I also agree that we need to be able to create tools that deal with software systems more easily. But I also think two other perspectives are important: - One is the historical perspective. The code-base is rarely a coherent whole. Two different areas may accomplish similar things with different tactics. The design of a component may be ill-suited to the way it is now being used. What is an intentional choice, and what is an accident? Which past choices should my current project align with? We typically read the code as it exists currently, and look at specific parts of the history only as a supplement, because even visualizing history is complex. But understanding why choices were made, and in what context, can be critical to knowing which things can now be changed. - The other is that reading code shows us a complex intensional definition, and reading tests gives us a partial view of an extensional definition (in case X we get behavior Y). But to "understand" programs enough to proficiently change them, we have to grokk something like the neighborhood around our current program: How would a given change in the code change the behavior? Being able to interactively change and re-run a program, and compare behavior before and after is in some sense like doing finite difference method differentiation.

anaerobicover 6y ago
One thing I've found can help somewhat with the historical aspect is putting reasons for particular choices in commit messages. Including small choices, decisions that are subcomponents of the reason for the whole patch. They are forever attached exactly to that diff, and can sometimes let a spelunking maintainer differentiate accident, entropy, and intention.
- Jefro118 6y ago
  Curious what you think of something like this: https://qualex.dev https://qualex.dev to solve the problem of incomplete commit messages?
  - anaerobicover 6y ago
    Interesting. I'm not so fussed about the formatting, and the ticket number is easy to catch with a git hook. But the "ask for more details" is definitely what I'm after.
tudorgirba 6y ago
Thanks for your thoughts. The post explicitly says that assessment (comprehension with the purpose of making a decision about a situation around a system) is not reading. However, it does says that people currently conflate the two because nobody talks about them to the point that reading is a proxy to measure comprehension effort. You are correct in saying that I argue that it is not appropriate to employ reading as a main means for assessment. Code is certainly not literature, but it should still be studied. In fact, assessment specifically talks about the intent. If the intent is different, such as learn a new language, reading is appropriate. Reading is also appropriate when the problem fits on one screen. It starts to be inappropriate as soon as you start to scroll. I also do not say that tools should be limited to code either. Every aspect of a system, including its history, runtime, tickets, customer feedback, is data, and it's all relevant. We should be easily able to integrate any of these in our reasoning. I agree with the observation that code can vary greatly. In fact, it is for very reason that out-of-the-box-clicking-tools will always fail to provide meaningful value. They bake the question in the click, but because of context is unpredictable, we simply do not know the question before we have the problem. That is why the specific tool we'd need should come after the problem, not before it. And yes, a system is a phenomena that should be approached through the scientific method (this is the essence of what moldable development is). Developers are already doing that implicitly. We should just make it explicit. All sorts of possibilities will arise after that.
- abeppu 6y ago
  IDK why someone downvoted you. Thanks for these thoughts. I guess I would only add the distinction that you're discussing "comprehension with the purpose of making a decision about a situation around a system". But sometimes we legitimately want to build comprehension without yet having a specific purpose or decision (e.g. when onboarding a team with an existing code base, or trying to understand how a technique works), but even then reading is a tempting but inadequate path to building understanding.
  - tudorgirba 6y ago
    Indeed. You are raising an important point. When you do not have a hypothesis, the first thing you want to do is get one :). It's like in research: the greatest problem you can have is not having a problem. Now, how do you get a hypothesis? You can start from some generic visualizations. The goal here is not to gain understanding, but to poke at finding interesting initial questions. But, you actually always know something. You likely know the domain. Or you know the last tickets that are in the work. Even listening in the casual conversations is a good starting point. When we train people, we literally start from the very issue they work on. Within 15 minutes, we typically find an interesting hypothesis to check for. For example, a dialog could go like this: A: What do you work on? B: A UI refreshing bug. A: What do you think happens? B: I do not know. A: Why are you looking at this specific screen? (this is a key question. people often do not know why this screen and not another. If you have a 250000LOC system, you likely have some 5000 other screens you could potentially look at. Not knowing why this one is potentially interesting is not a good thing) B: Because I think maybe it's related to how we subscribe to events. A: How do you expect the event subscription to be like? B: It should always happen in a method called xyz that is provided by the framework. A: In all classes? B: A, no. Just in components. A: Ok, so you want to know the event handling that are not defined in xyz in subclasses of the component superclass. B: A, right. It's actually remarkably straightforward. Just try it.

by abeppu 6y ago

anaerobicover 6y ago

One thing I've found can help somewhat with the historical aspect is putting reasons for particular choices in commit messages. Including small choices, decisions that are subcomponents of the reason for the whole patch. They are forever attached exactly to that diff, and can sometimes let a spelunking maintainer differentiate accident, entropy, and intention.

Jefro118 6y ago
Curious what you think of something like this: https://qualex.dev https://qualex.dev to solve the problem of incomplete commit messages?
- anaerobicover 6y ago
  Interesting. I'm not so fussed about the formatting, and the ticket number is easy to catch with a git hook. But the "ask for more details" is definitely what I'm after.

tudorgirba 6y ago

Thanks for your thoughts. The post explicitly says that assessment (comprehension with the purpose of making a decision about a situation around a system) is not reading. However, it does says that people currently conflate the two because nobody talks about them to the point that reading is a proxy to measure comprehension effort. You are correct in saying that I argue that it is not appropriate to employ reading as a main means for assessment. Code is certainly not literature, but it should still be studied. In fact, assessment specifically talks about the intent. If the intent is different, such as learn a new language, reading is appropriate. Reading is also appropriate when the problem fits on one screen. It starts to be inappropriate as soon as you start to scroll. I also do not say that tools should be limited to code either. Every aspect of a system, including its history, runtime, tickets, customer feedback, is data, and it's all relevant. We should be easily able to integrate any of these in our reasoning. I agree with the observation that code can vary greatly. In fact, it is for very reason that out-of-the-box-clicking-tools will always fail to provide meaningful value. They bake the question in the click, but because of context is unpredictable, we simply do not know the question before we have the problem. That is why the specific tool we'd need should come after the problem, not before it. And yes, a system is a phenomena that should be approached through the scientific method (this is the essence of what moldable development is). Developers are already doing that implicitly. We should just make it explicit. All sorts of possibilities will arise after that.

abeppu 6y ago
IDK why someone downvoted you. Thanks for these thoughts. I guess I would only add the distinction that you're discussing "comprehension with the purpose of making a decision about a situation around a system". But sometimes we legitimately want to build comprehension without yet having a specific purpose or decision (e.g. when onboarding a team with an existing code base, or trying to understand how a technique works), but even then reading is a tempting but inadequate path to building understanding.
- tudorgirba 6y ago
  Indeed. You are raising an important point. When you do not have a hypothesis, the first thing you want to do is get one :). It's like in research: the greatest problem you can have is not having a problem. Now, how do you get a hypothesis? You can start from some generic visualizations. The goal here is not to gain understanding, but to poke at finding interesting initial questions. But, you actually always know something. You likely know the domain. Or you know the last tickets that are in the work. Even listening in the casual conversations is a good starting point. When we train people, we literally start from the very issue they work on. Within 15 minutes, we typically find an interesting hypothesis to check for. For example, a dialog could go like this: A: What do you work on? B: A UI refreshing bug. A: What do you think happens? B: I do not know. A: Why are you looking at this specific screen? (this is a key question. people often do not know why this screen and not another. If you have a 250000LOC system, you likely have some 5000 other screens you could potentially look at. Not knowing why this one is potentially interesting is not a good thing) B: Because I think maybe it's related to how we subscribe to events. A: How do you expect the event subscription to be like? B: It should always happen in a method called xyz that is provided by the framework. A: In all classes? B: A, no. Just in components. A: Ok, so you want to know the event handling that are not defined in xyz in subclasses of the component superclass. B: A, right. It's actually remarkably straightforward. Just try it.