Neal ford also states, that code should be written in such a way, that comments are not needed.
I translate this to "code should be as clear and simple as it can". But this only obviates comments that explain WHAT the code does. The more valuable comments are about WHY the code does what it does;
why did the developer choose this algorithm over that one.
And this kind of comment IMHO should not be invalidated by refactoring. Refactoring (as I understand it) only changes notation without changing visible behaviour. Thus, the design decisions should not be changed by refactoring.
Of course, if the design decisions change, the comment needs updates. But the alternative is, to NOT record the design decision.
2008-11-08
Whats the goal of Literate Programming?
Neal Ford posted an article on Meme Agora, where he postulated, that Literate Programming pursued the goal of self-documenting code, in the sense that the code IS the documentation.
Literate Programming as I understood the concept is NOT about avoiding documentation. It is about putting documentation FIRST and code second, because making code readable for humans is the more difficult and more important thing.
It should be possible to structure your program in such a way, that a narrative appears and that the program is presented to a reader in the way that is easiest to understand. This should not be limited by the available means of the programming language.
Obviously this is more important when writing software in languages that impose structure (e.g. "declare all variables at the top of your function") than in languages that allow more freedom.
Also it is a more document-oriented approach, where it is assumed, that the narrative is created by one authorative voice and not the collaborative fashion in which programs are created nowadays.
Literate Programming as I understood the concept is NOT about avoiding documentation. It is about putting documentation FIRST and code second, because making code readable for humans is the more difficult and more important thing.
It should be possible to structure your program in such a way, that a narrative appears and that the program is presented to a reader in the way that is easiest to understand. This should not be limited by the available means of the programming language.
Obviously this is more important when writing software in languages that impose structure (e.g. "declare all variables at the top of your function") than in languages that allow more freedom.
Also it is a more document-oriented approach, where it is assumed, that the narrative is created by one authorative voice and not the collaborative fashion in which programs are created nowadays.
Abonnieren
Posts (Atom)