While this paper proposes a new system of programming more closely tied to documentation, it brings up the topic of documentation on a more general level. This is truly an area of computer science that rarely receives the attention or the emphasis it deserves.

Learning to code and design are certainly goals which should be stressed in an introductory course, but documenting that code and design is an equally important skill. It's important not only to be able to convey the message to the machine (or VM), but to whatever people happen to read that code.

CS15 forces some ability to document onto the students, but never teaches it as a skill comparable to designing or to implementing design. As program size grows, it becomes increasingly important for not only those trying to interpret the student's effort, but for the student himself to be able to clearly determine the goal of a code segment. In group oriented courses, such as cs32, this skill becomes even more vital; it would be best if it could be taught early a student's programming career.

In cs15, students are never really exposed to well documented code. A perfect implementation of this would be in the GP source where students could look for examples of what excellent documentation is. This is a topic for discussion at another time, but GP could be not just a tool for learning OO, but one for learning style in code and documentation.

The WEB system described in the article at first struct me as foolish: is mixing a formatting language and a programming language really such a good idea? But then I realized that that is exactly what exists in java/javadoc and what is used in wave. The mixture of HTML and java is really useful for reading through a class description without looking at actual code. (This is especially interesting given the name of the author's environment and the nature of HTMl and java) Perhaps students should be taught to use HTML in their documentation or at least the javadoc specific tags which can make the class descriptions more useful and readable. Again the GP documentation could be a good place to show off the uses of HTML and javadoc.

Even more generally, the article discusses programming environments which is a topic which may beg further discussion. Perhaps we should look at what's currently available if not to replace wave then to integrate into it.

MY COMMENTS

Again I wonder how useful it is to automatically think 'CS15' as soon as we read soemething. Surely I am guilty of it as well, and it is understandable since this is the one area we all share in common and which we would like to apply things to. However, I think we should be reading these papers and commenting on them in and of themselves.

Keeping this in mind, what does the addition of documentation to the programming process have to offer to the programmer as well as the user and developer? Does Knuth prove his point?

I think what he says is pretty valuable. It may in fact be true that programmers do take short cuts in their programming because it doesn't look right to obfuscate something that should be a relatively simple method (when he is talking about error correction). Introducing documentation into the process, he claims, makes programmers feel more at ease with writing the full programs that they should because they look better in the combined environment.

Understanding that the learning curve for an environment like this is large (as it is comprised of four languages), it may well be a good tool for advanced computer scientists, as the author mentions. Instead of just thinking about this concept as the importation of a new tool, is there anything important about documentation that is being missed?

I feel that if anything, we can see that perhaps the documentation process is a bigger part of programming then it may currently be thought. Rather then think about documentation as something you do to your program perhaps we should be thinking about documentation as part of our program. Maybe it is just a question of semantics, and how we think about it that effects our current opinions of documentation.

MY COMMENTS

I agree that commenting and documentation are important skills for people to learn, but I disagree that documentation should be taught to be separate from the programming itself. When you program, you should document your code, not rely on other languages to create nicer looking documents for you. Java is different in that html could be used to make documentation, but many other languages lack this feature. It would be better to teach students about standard documentation procedures, so that no matter where they end up they know how to document code without the help of Wave Java docs, or documenting languages.

MY COMMENTS You bring up an interesting point. JavaDoc does allow people to successfully create easy-to-read documentation for their programs but I see one major problem with it. People have no idea what should be included in documentation. Very rarely do people concisely explain their design or even their code. Without understanding what to write, tools for commenting are of no use.