6 ms·

Once a program has been developed and the developers have moved on to other tasks it needs to be maintained. The fundamental problem is that if you modify code

by daly 5y ago

Once a program has been developed and the developers have moved on to other tasks it needs to be maintained. The fundamental problem is that if you modify code you didn't write, you don't see the big picture and you don't understand the reasons why the code is written the way it is. Thus changing code without a larger context is almost always going to introduce new bugs. The only way to correctly change code is to deeply understand the implications of the change. This requires a deep understanding of the code and an awareness of the big picture. Yet the "why" of code is rarely ever written down in standard programming practice. The goal is only to elaborate the "how" so the machine can perform the task. The programmer communicates with the machine. Literate programming, as used in Axiom, is an attempt to communicate with other users, developers, and researchers in addition to the machine. The goal is to have the program read like a story so that others can understand the rational, the theory, the choices, the implications, and the implementation context as well as the "how". This code is intended to live forever but it is highly probable that you will not. Write to communicate with the next person to pick up the torch. When you explore code, write down what you learn. When you change code, explain why you made your choices. When you write new code explain what others need to know to maintain it.

emodendroket 5y ago
My very strong suspicion is that a program written in the “literate” style and then maintained a long time is very likely to end up with its comments and implementations disagreeing, making it worse, in this respect, than one without comments. I say this because this has been my observation even with much more modest amounts of comments. Keeping them in sync with the code is always a struggle.
- akkartik 5y ago
  That is, for me, the genius of LP. It's not just a "style" you garnish on top of your code. When you do LP you become more likely to reread the documentation as you maintain the program. Which makes it easier to keep it up to date. On the other hand, all the LP programs I've seen were built by people who care about documentation. Perhaps we would have managed to keep things up to date even without LP. There may be a selection bias here. Either way, I'd say you don't know what you're talking about when it comes to daly's Axiom (http://axiom-developer.org http://axiom-developer.org). It doesn't just end up with outdated comments, that's a serious charge to level without concrete evidence. Similarly, I'd be extremely interested in outdated comments in https://github.com/akkartik/mu/tree/main/linux/bootstrap https://github.com/akkartik/mu/tree/main/linux/bootstrap which is written in the LP style I described in OP. I consider outdated comments to be bugs.
  - Someone 5y ago
    The main problem with maintenance of programs is that, when changing an assumption ‘deep down’ in the code, about nobody is going to check the chain of logic from there throughout the code. IMO, LP-style programming doesn’t change that. If the problem happens less with programs written in LP-style, I agree with you chances are it’s because people who write in that style tend to be more careful. What would change it is to require programmers to supply proofs about their code. Unit tests don’t guarantee that, but have the benefit of being easier to write.
    - akkartik 5y ago
      But you're expanding the scope now. Yes, LP isn't going to guarantee you always preserve semantics in any change. But hopefully we can agree that it's not going to make it more difficult. Unit tests or proofs are extremely useful. You should still have them in Literate programs! They're complementary tools. My Literate system does explicitly assume tests unlike earlier systems I was dissatisfied with. Check out all the tests in https://github.com/akkartik/mu/tree/main/linux/bootstrap https://github.com/akkartik/mu/tree/main/linux/bootstrap. For example, https://github.com/akkartik/mu/blob/main/linux/bootstrap/013direct_addressing.cc#L7 https://github.com/akkartik/mu/blob/main/linux/bootstrap/013...
- strictfp 5y ago
  I have to object here and say that out-of-date comments are better than no comments. I've worked in organizations with "no comments" policies and having no clue what people ever planned to achieve with a piece of code is worse than some old misguided explanation for sure.
  - emodendroket 5y ago
    I wouldn’t support a no-comment policy, but I’ve wasted a lot of time thanks to misleading comments.
    - hiptobecubic 5y ago
      You have to assume that comments are out of date, then it's easier to make use of them.
      - emodendroket 5y ago
        But out of date in which way? It could be anything from some extra cases to literally the opposite of what the comment says to the code has changed so much it’s not even clear what the comment refers to anymore.
    - jimmyvalmer 5y ago
      Notices a kindred spirit You get it. I get it. Unfortunately every intro class inculcates generous commenting, a "best practice" further promoted by corporate proceduralists and mediocre programmers who inexorably become managers. A comment longer than 160 characters is always weak-sauce justification for logic written awkwardly.
      - emodendroket 5y ago
        For the most part comments I appreciate are something like "the obvious thing here is xyz, but we can't do that because of this goofy limitation of software we're integrating with."
- User23 5y ago
  This is mainly a problem for “how” comments and less so for “why” ones. “How” comments are almost always worthless at best, but “why” comments are vital for large code bases. Literate programming should consist of “why” comments and if the why changes and thus the implementation does, the commentary ought to as well.
- yissp 5y ago
  There are a few of these longer, explanatory comments in the code-base I currently work on, and while we do generally try to keep them up-to-date, personally I find they've become difficult to read. As the code evolves you have people trying to splice sentences into the middle of a paragraph, different people have different writing styles, some aren't native English speakers. Unless you're willing to rewrite the whole thing every time you make a non-trivial change it seems to end up a bit of a mess. As one co-worker put it "you need to read the code in order to understand the comments".
secondaryacct 5y ago
You're right if juniors take over, but with experience I've learned to understand that things are done a certain way for a reason. Sometimes they didnt see a bigger pictures but many time they did and something blocked them from solving the problem Im trying to solve in maintenance mode. Commenting too much in the code simply makes my work impossibly hard because I need to juggle with contradictory statements. I ve found that always committing with a ticket reference and keeping tickets forever allows me to go back sometimes decades ago to understand the problem they were solving at the time, for each layer of the code im looking at (each line having an history). I read comments now with suspicion as sometimes the comment is a commit 20 years ago and the associated line is 5 years old. Should it have always been kept in sync ? Yes. Could it have been ? I've never seen it done properly.
- hiptobecubic 5y ago
  Having no comment at all is strictly worse than having one you're suspicious of and are free to ignore. Leaving good, durable comments is a skill you learn over time, but the solution is not to tell juniors to leave none.

by daly 5y ago

emodendroket 5y ago

My very strong suspicion is that a program written in the “literate” style and then maintained a long time is very likely to end up with its comments and implementations disagreeing, making it worse, in this respect, than one without comments. I say this because this has been my observation even with much more modest amounts of comments. Keeping them in sync with the code is always a struggle.

akkartik 5y ago
That is, for me, the genius of LP. It's not just a "style" you garnish on top of your code. When you do LP you become more likely to reread the documentation as you maintain the program. Which makes it easier to keep it up to date. On the other hand, all the LP programs I've seen were built by people who care about documentation. Perhaps we would have managed to keep things up to date even without LP. There may be a selection bias here. Either way, I'd say you don't know what you're talking about when it comes to daly's Axiom (http://axiom-developer.org http://axiom-developer.org). It doesn't just end up with outdated comments, that's a serious charge to level without concrete evidence. Similarly, I'd be extremely interested in outdated comments in https://github.com/akkartik/mu/tree/main/linux/bootstrap https://github.com/akkartik/mu/tree/main/linux/bootstrap which is written in the LP style I described in OP. I consider outdated comments to be bugs.
- Someone 5y ago
  The main problem with maintenance of programs is that, when changing an assumption ‘deep down’ in the code, about nobody is going to check the chain of logic from there throughout the code. IMO, LP-style programming doesn’t change that. If the problem happens less with programs written in LP-style, I agree with you chances are it’s because people who write in that style tend to be more careful. What would change it is to require programmers to supply proofs about their code. Unit tests don’t guarantee that, but have the benefit of being easier to write.
  - akkartik 5y ago
    But you're expanding the scope now. Yes, LP isn't going to guarantee you always preserve semantics in any change. But hopefully we can agree that it's not going to make it more difficult. Unit tests or proofs are extremely useful. You should still have them in Literate programs! They're complementary tools. My Literate system does explicitly assume tests unlike earlier systems I was dissatisfied with. Check out all the tests in https://github.com/akkartik/mu/tree/main/linux/bootstrap https://github.com/akkartik/mu/tree/main/linux/bootstrap. For example, https://github.com/akkartik/mu/blob/main/linux/bootstrap/013direct_addressing.cc#L7 https://github.com/akkartik/mu/blob/main/linux/bootstrap/013...
strictfp 5y ago
I have to object here and say that out-of-date comments are better than no comments. I've worked in organizations with "no comments" policies and having no clue what people ever planned to achieve with a piece of code is worse than some old misguided explanation for sure.
- emodendroket 5y ago
  I wouldn’t support a no-comment policy, but I’ve wasted a lot of time thanks to misleading comments.
  - hiptobecubic 5y ago
    You have to assume that comments are out of date, then it's easier to make use of them.
    - emodendroket 5y ago
      But out of date in which way? It could be anything from some extra cases to literally the opposite of what the comment says to the code has changed so much it’s not even clear what the comment refers to anymore.
  - jimmyvalmer 5y ago
    Notices a kindred spirit You get it. I get it. Unfortunately every intro class inculcates generous commenting, a "best practice" further promoted by corporate proceduralists and mediocre programmers who inexorably become managers. A comment longer than 160 characters is always weak-sauce justification for logic written awkwardly.
    - emodendroket 5y ago
      For the most part comments I appreciate are something like "the obvious thing here is xyz, but we can't do that because of this goofy limitation of software we're integrating with."
User23 5y ago
This is mainly a problem for “how” comments and less so for “why” ones. “How” comments are almost always worthless at best, but “why” comments are vital for large code bases. Literate programming should consist of “why” comments and if the why changes and thus the implementation does, the commentary ought to as well.
yissp 5y ago
There are a few of these longer, explanatory comments in the code-base I currently work on, and while we do generally try to keep them up-to-date, personally I find they've become difficult to read. As the code evolves you have people trying to splice sentences into the middle of a paragraph, different people have different writing styles, some aren't native English speakers. Unless you're willing to rewrite the whole thing every time you make a non-trivial change it seems to end up a bit of a mess. As one co-worker put it "you need to read the code in order to understand the comments".

secondaryacct 5y ago

You're right if juniors take over, but with experience I've learned to understand that things are done a certain way for a reason. Sometimes they didnt see a bigger pictures but many time they did and something blocked them from solving the problem Im trying to solve in maintenance mode. Commenting too much in the code simply makes my work impossibly hard because I need to juggle with contradictory statements. I ve found that always committing with a ticket reference and keeping tickets forever allows me to go back sometimes decades ago to understand the problem they were solving at the time, for each layer of the code im looking at (each line having an history). I read comments now with suspicion as sometimes the comment is a commit 20 years ago and the associated line is 5 years old. Should it have always been kept in sync ? Yes. Could it have been ? I've never seen it done properly.

hiptobecubic 5y ago
Having no comment at all is strictly worse than having one you're suspicious of and are free to ignore. Leaving good, durable comments is a skill you learn over time, but the solution is not to tell juniors to leave none.