Computer Science Teacher
Computer Science Teacher - Thoughts and Information from Alfred Thompson

June, 2007

  • Computer Science Teacher - Thoughts and Information from Alfred Thompson

    Programming Proverbs 20: Provide good documentation


     Well what in the world is good documentation? Now there is a question for the ages. Lots of programmers hate to document their work. I've heard more than a few programmers over the years say things like "you want documentation? Read the code. The code is self explanatory." Ah, yeah, right.

    Most will agree to some level of comments - what we generally refer to as internal documentation. If you read some of the comments about comments in my earlier post on that subject you'll find plenty of disagreement about that subject. The question of documentation is a little more complicated than that as soon as you realize that there are several types of people involved. There are other programmers who may have to debug, extend or enhance a program. But there are also various types of users who have to use the program. In some organizations there are also people whose job it is to test the software. All of those groups require different types of documentation and different pieces of information.

    The amount of documentation and who creates it often depends on the size of the project and the size of the organization. In large professional organizations the people who create user documentation are often specialized technical writers and not programmers at all. But let us focus here on documentation by and for programmers.

    I think that the minimum documentation for a piece of code is the list and description of:

    • inputs - names, types and purposes
    • outputs -  types being the most important piece
    • algorithm descriptions

    Generally this can be in a comment block at the top of the method/function/routine but it can be valuable to collect the descriptions from all code blocks into a central document. This information allows a programmer to determine, as long as they assume the code works as advertised, to determine if if meets their needs and how they can use it. If a programmer is going to modify or test that code they have enough information to determine what the code does. Or at least what it is supposed to do. Someone pointed out that comments like but code doesn't. In this case a good set of comments allows one to check the code against the comments to understand where things might have gone wrong.

    I like pictures -  call them diagrams if you like. I'm an engineer by way of how I think of myself and that means I'm something of a visual person. That is one of the reasons I like tools like the Class Designer in Visual Studio (not available in the Express Editions unfortunately). Besides letting a programmer create the stubs for methods, properties and the like for a class this tool also allows the programmer to show the relationships between different classes. There are other tools available for showing the relationships between different parts of databases. Either drawn using tools or drawn by hand I think that relationship and other diagrams can be a very useful and important part of project documentation. Visual people will see things much quicker viewing an image than reading code.

    Of course keeping the documentation updated is always a problem. That makes tools like the Visual Studio Class Designer more valuable. Just as updates to the Class Designer are reflected in the code generated so are changes made directly to the code available automatically in the Class Designer.

    Years ago (many years ago) a professor of mine handed me a large deck of cards for a graphic programming library. He said that this was a great library but that the university had no documentation for it. There were not even many comments. No one could use the library, at least not easily, without some documentation. My job was to create that documentation. It was not an easy task but it sure did convince me of the value of documentation. The old line is that the job is not done until the paperwork is done. For programming documentation is the paperwork.

    This is the twentieth of a series of posts based on the book Programming Proverbs by Henry Ledgard. The index for the series is an earlier post and discussion of the list as a whole is taking place in the comments there. Comments on this "proverb" are of course very welcome here.

  • Computer Science Teacher - Thoughts and Information from Alfred Thompson

    Math Moves U - And a Mission to Mars


    I recently found out about MathMovesU as web site devoted to mathematics. Specifically someone told me about the Mission to Mars contest they are running in conjunction with the upcoming Mars Day.

    July 20 is Mars Day at the Smithsonian National Air and Space Museum and MathMovesU has released an edu-game to celebrate the event called the MathMovesU Mission to Mars. In the game, players will encounter and learn about different landmarks on Mars by completing Mars related math problems.

    Competitors who get to Mars will be entered in a drawing for a chance to win a wide range of prizes, from a family trip to Washington D.C. to celebrate Mars Day with a VIP tour of the Smithsonian National Air and Space Museum to an acre of land on Mars, a Sony PS2 and more!

    I always appreciated the connection between math and other sciences but one of the cool things about this web site is how it makes connections to celebrities in many fields, including the arts and sports, to mathematics. MathMovesU is sponsored by Raytheon where they believe that tomorrow's engineers and technologists need to be excited by and interested in math today. I couldn't agree more!

  • Computer Science Teacher - Thoughts and Information from Alfred Thompson

    Computer Science Mythbusters


    Over at Millikin University the CS department has collected a set of myths about computer science and responses.

    Myth # 1: There are no jobs! They've all been outsourced overseas...
    Myth # 2: Computer Science is just programming...
    Myth # 3: Computer Scientists are loners, chained to a computer.
    Myth # 3: Computer Science doesn't pay that well. 
    Myth # 4: Computer Science is not relevant.

    It is amazing to me that we even need to have myth buster pages for tales like those but in fact we do.There is a lot of FUD out there. There are lots of jobs, CS is more than programming, most computer scientists are regular people who lead very social lives, computer science can pay very well indeed and of course CS has never been more relevant or part of everyones daily life then it is today. Check out the longer answers with links to supporting data at

    And of course computer science is a whole lot of fun as well. Why does everyone forget to talk about the fun part!

Page 5 of 8 (24 items) «34567»