Code Documentation Dichotomy
Code Documentation DichotomyRegarding the LiterateProgramming discussion:
Reflecting upon the meanings and implications of a distinction between code and documentation...
I don't see the logic in deriving the last statement. Source code is entirely for human consumption. The compiled binary is for machine consumption. The source code and binary are highly coupled, and for all practical purposes have a 1 to 1 relationship.
Right. Very. Why then the Extremists (and others) say "The code is the documentation"? That's the binarism XP, and LP before them, sins in committing.
Well hang on right there -- surely the variable part is that source code and binary are highly coupled, and for all practical purposes have a 1 to 1 relationship. The aim should then be to decouple those two as much as possible -- use layers of abstraction, whitespace, variable names (all the things which can be varied without affecting the binary) to make the source code more like documentation, and less like assembler. Thus the source code fulfills the role of documentation better, while still being perfect for the machine too. --PaulMitchellGears
I think we want to maintain the coupling of the source code to the compiled executable. When what I read in the source code diverges from what the computer in execution, it leads to either confusion on my part or an error in the program.
Hmm. This "entirely", above. Doubt it, really: programming is writing instructions to a machine, primarily (oh? an hierarchy? :o), and to other programmers (oneself included), by necessity. Maybe? Contemplating...
Perhaps we need to expand this discussion back into the larger realm of defining the difference between code and documentation. Documentation can never be said to be aimed at a machine, whereas code may be defined that way or not. How do we set boundaries on this discussion? What are the base definitions that all here can agree to?
Additionally, are there more pages where this discussion (obviously ThreadMode) is going on and can we combine some of these discussions? Is there already a DialecticMode discourse on this very subject hiding somewhere on this Wiki?
- Code has meaning for the computer
- Documentation has meaning for people
These are not incompatible: the code can be the documentation, if people can readily extract meaning from it.
This is similar to what AlistairCockburn says in AgileSoftwareDevelopment -- documentation is sufficient if it allows the people reading it to proceed with their work.
Also, the code is preferable to other documentation forms, because it is known to match the code. Other forms of documentation generally require checking against the code, because they often don't match. --DougKing
Yah, well, there's the rub, eh? Why do some folks insist that the code is "right," even if it disagrees with the docs? If a design doc says that two modules have such-and-such an interface and some hacker makes his blessed code do something different, then the code is wrong. This business of going back to "correct" the docs after the code has been hacked out is wrong-headed.
The code may not be "right", but it is true. If your tests prove your code to be wrong, then fix the code. If your code is also your documentation, you can fix both at the same time.
Source code prescribes what the program will do, where as documentation only describes what we think it will do.
Documents tell someone other than a coder what the app will do. If the app does something other than what the doc says then the app is wrong, period. I guess that's what tests are for, eh? However, tests can be wrong themselves and so don't necessarily reflect the content of the document as understood by non-technical people.
Why should the documentation be assumed to be correct? Is there any reason to believe the documentation writers are less fallible than software writers? Isn't the executable program far more understandable to non-technical people than the documentation?
The documentation must be assumed to be correct because something must be. Some one thing. Exactly one thing, and that thing is the document from which the code was created. If there is no single guiding construct to tell us what is correct, then everybody who touches this mess will interpret needs and results in their own way, leading to a useless collection of kaka.
There are different kinds of documentation. Which kind are we discussing here?
-- BrentNewhall
How can you assert the design documentation is correct? The written design document has just as much chance of being wrong as the developed code. The most correct evaluation one can receive is the responses of those people trying to use the system.
Presumably, the design document is a record of what the customer wants (I'm using the term "customer" in the broad sense of the individual(s) who drive the creation of the system). If the code does not do what the customer wants, the code is wrong. (Obviously, there are cases where the code just can't be made to do something. That's a special case, and not germane to the general point being made here.)
I believe that the design document has less chance of being wrong than the developed code, because the code is written to comply with the design document, and the customer wrote or signed off on the design document. The design document is closer to the customers' desires than the code.
-- BrentNewhall
What if instead of writing a prose document to record the customer's wants, you just write the code? The code is far easier for the customer to evaluate for correctness. Just because a customer signs a document does not make the information correct, except as a legal document. The example above of creating an intermediate information source just highlights the problems with relying on documentation.
On the contrary, it is extremely useful to describe how the system works. If you joined a team that's working to upgrade a 5 million LOC program, wouldn't you benefit from a document that describes how the system actually works? -- BrentNewhall
Not if the team already knows how the system works and the culture encourages asking questions. It's much more efficient to look at the code and ask questions. Plus, if the project is under active development, the cost of continually maintaining the documentation is probably more than the cost of answering newbie's questions. --JimLittle
I take that back. Sort of. An overview, no more than five pages, with basic concepts and a high-level design diagram might be cost effective. Maybe. Depends on the amount of turnover. --JimLittle
Programmers benefit far more from seeing how the program is or is to be used than from any written documentation. To send one programmer to the field for a week would run about $3000 ($1000 airline tickets, 5 x $200 a day in expenses, $1000 in salary). The programmer will learn far more of the details and nuances important to the users than could ever be conveyed in a written document.
How much would it cost to write the document? And what about aspects of the system that aren't revealed by using it (for example, a week of using an e-mail application would not reveal how it stores the e-mails)? -- BrentNewhall
Assuming this section is discussing user documentation, why should the user care how e-mail is stored? If this level of detail is included in user documentation, it would appear to be doubtful that the document would be "no more than five pages."
Code is a specialized documentation, understandable to an esoteric few. Although the documentation in code is true, it is very difficult to get to the bigger picture just by looking at the documented code. Both a conventional top level documentation and the documentation in code are required. Detailed documentation about implementation of the program is best done in code; while abstract and high level documentation is better done in conventional style. -- VhIndukumar
Far more people, probably at the level of orders of magnitude, run the code versus those who read the documentation. Documentation only serves to fill the gaps in the quality of the code.
Look at JUnit test suit. It's well written; but if you do not have a How To or a high level document that gives an overview of its working, it is difficult to follow it. Looking at code to get overall picture is a Bottom Up approach. Its much more difficult to get the Big Picture. You will be looking at trees and wondering where the forest is. -- VhIndukumar
How can you say both "It's well written" and "it is difficult to follow?" The latter seems to contradict the former.
The Brothers Karamazov is well-written, but is difficult to follow. While difficulty of comprehension may suggest that the code is poorly written, that's not necessarily true. -- BrentNewhall
So what would the definition of "well-written" as applied to software source code that would permit it to be both well-written and hard to understand?
I recently found an interesting, but opposite approach to the same question. I found a piece of code that had a long comment in it explaining what was happening in terms of variables. ("Because of the if (a) { above, we can assume that b is also true"), and it got me thinking about the reverse problem: People writing documentation where code would have been better. I replaced the above with an assert() and an explanation why. Now the compiler can use that information and perhaps use it for optimisation. -- PerryLorier
EditText of this page
(last edited April 15, 2013)
or FindPage with title or text search