alt Hacker NewsCode doesn't express intent, only the implementation. Docblocks are fine for specifying local behavior, but are terrible for big picture things.
Replies
anotheryou • yesterday at 9:46 PM
right you are :)
does literate code have a place for big pic though?
Well many times it does.
bool isEven(number: Int) { return number % 2 == 0 }
I would say this expresses the intent, no need for a comment saying "check if the number is even".
Most of the code I read (at work) is not documented, still I understand the intent. In open source projects, I used to go read the source code because the documentation is inexistent or out-of-date. To the point where now I actually go directly to the source code, because if the code is well written, I can actually understand it.