4 ms·

I'm interested to see where this goes, but one of the problems with literate programming is that it means that in addition to being a good programmer you also n

by gfodor 14y ago

I'm interested to see where this goes, but one of the problems with literate programming is that it means that in addition to being a good programmer you also need to be a good writer. In other words, if you are a good programmer and a bad writer you are going to produce net bad work since your writing will confuse people who might otherwise have understood the code on its own, and if you are a good writer and a bad programmer there is a chance this will make it harder for others to realize your implementation sucks since it may be dressed in the most brillant, clear prose possible. (Of course one can make the argument that brilliant clear prose is a sign of brilliant clear thinking and hence code, but I am not so sure.) It also opens up the door for an entirely new dimension in code reviews. Imagine your resident grammar nazi jumping into code reviews now to perform edits to paragraphs upon paragraphs of comments. (This is probably the same person who agonizes over class names, so maybe you're already used to this :)) I've found that there seems to be a decent correlation with writing skills and programming skills, but that's far from a fact and I've worked with people in every spot in the 2x2 skills matrix.

jashkenas 14y ago
> This is probably the same person who agonizes over > class names, so maybe you're already used to this Bingo. I think that for programming languages where clarity is already a common virtue (think, Ruby, Python, Clojure) -- folks already need to be writing clearly when they program: making the code clear to read, naming variables and functions very well, doing logical ordering of sections of code etc. That's already about halfway towards what you would do if you were accompanying the code with a bit of essay. I think the two worlds aren't as far apart as one might think.
crazygringo 14y ago
> one of the problems with literate programming is that it means that in addition to being a good programmer you also need to be a good writer To be a good team programmer, you already need to be a good communicator, and being a good writer is part of that. In my opinion, it's one of the biggest things that separate programmers who only work well on their own, and programmers who work well as part of a team project. It's not about grammar, it's just about clarity and explaining things well. But it's also not something you're born with, it's something anyone can learn, if they want to.
mcgwiz 14y ago
I disagree. No one's asking for a literary masterpiece, just a simple and organized explanation of what we're looking at. I would argue that the value is more in the process of creating this simple explanation, because it forces you to empathetically examine the code from a a foreign mindset, and from there to re-order and organize the code in a way that's amenable to conversational (simple) explanation. This explanation may include requirements and other concerns, description of alternatives and why they were rejected, references to other parts of the codebase, and its high-level design intention (i.e. vision) in order to guide the direction of refactorings and extensions. None of this requires analogy, symbolism, foreshadowing, subtlety of tone, or even a mastery of diction and syntax. Anything resembling Yeats or Dostoyevsky is counter-productive.

by gfodor 14y ago

jashkenas 14y ago

> This is probably the same person who agonizes over > class names, so maybe you're already used to this Bingo. I think that for programming languages where clarity is already a common virtue (think, Ruby, Python, Clojure) -- folks already need to be writing clearly when they program: making the code clear to read, naming variables and functions very well, doing logical ordering of sections of code etc. That's already about halfway towards what you would do if you were accompanying the code with a bit of essay. I think the two worlds aren't as far apart as one might think.

crazygringo 14y ago

> one of the problems with literate programming is that it means that in addition to being a good programmer you also need to be a good writer To be a good team programmer, you already need to be a good communicator, and being a good writer is part of that. In my opinion, it's one of the biggest things that separate programmers who only work well on their own, and programmers who work well as part of a team project. It's not about grammar, it's just about clarity and explaining things well. But it's also not something you're born with, it's something anyone can learn, if they want to.

mcgwiz 14y ago

I disagree. No one's asking for a literary masterpiece, just a simple and organized explanation of what we're looking at. I would argue that the value is more in the process of creating this simple explanation, because it forces you to empathetically examine the code from a a foreign mindset, and from there to re-order and organize the code in a way that's amenable to conversational (simple) explanation. This explanation may include requirements and other concerns, description of alternatives and why they were rejected, references to other parts of the codebase, and its high-level design intention (i.e. vision) in order to guide the direction of refactorings and extensions. None of this requires analogy, symbolism, foreshadowing, subtlety of tone, or even a mastery of diction and syntax. Anything resembling Yeats or Dostoyevsky is counter-productive.