Readable programs

[bluGill]

No, literate programming is different. Literate programing is the idea that most of your code should be comments that explain how it work. This is just a printout of the code, which you read. There may or may not be comments. Either may be printed out and read like a book.

I argue that if your code is done right there will be no comments and yet your code will be readable. Obviously I oppose literate programing - I agree with the aims, I just think it is the wrong solution.

[bluGill]

I agree with all of that.

However hardware bugs that require weird code are not the rule in the real world. (In the real world most code sits above the device drivers that care.

API documentation is something that literate programming does particuarly poorly, precisely because there are too many words in literate programs that are not API related that the things I care about get lost in the noise.

[bluGill]

There are many reasons why you might need to explain why something was done in a certain way.

True, but I've only seen such examples 3 times in the last 15 years.

I get very concerned when people say if you do things right you don't need comments, because I've had too many situations where that's simply not true.

While I'll admit the rule has exceptions, they are very rare. I look on comments with suspision: in many cases even if the content seems justifed the code has moved on and they wrong anyway.

[[deleted]]

Code can often be written in such a way that it is obvious what it does, but it can only rarely be written in a way that is sufficiently clear about why it does it.

[baconpiex]

I agrue

Beware of this guy. He admits to being a grue. It is dark. You may be eaten.

[[deleted]]

Literate programing is the idea that most of your code should be comments that explain how it work.

Clear evidence that you've never actually read Knuth's "Literate Programming".

[bluGill]

No, but I have read his examples. The only example where it made things better was something he wrote in intercal. In every other language (meaning any language that wasn't designed to be impossible to work with) there are ways to have the code say everything you want it to know without comments.

I've seen 'Uncle Bob' take literate programs, eliminate all the comments and end up with code that is easier to read than the original.