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

    • 2 Comments

     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

    Programmer Personality Test

    • 4 Comments

     I found this Programmer Personality test the other day. It is based of the Myers-Briggs Personality Test but obviously recrafted for programmers. Now I have mixed feelings about Myers-Briggs (my son  the psychology major dismisses it completely) but a lot of people put stock in it. This test, while it claims to be serious, has too few questions in my opinion to be reliable enough for serious evaluations. And of course I am unaware of any real research behind it. On the other hand it was quick and easy to take and I found the results interesting. My results are below. My comments on the results are below that. 

    Your programmer personality type is:

       PHSB

    You're a Planner.
    You may be slow, but you'll usually find the best solution. If something's worth doing, it's worth doing right.


    You like coding at a High level.
    The world is made up of objects and components, you should create your programs in the same way.


    You work best in a Solo situation.
    The best way to program is by yourself. There's no communication problems, you know every part of the code allowing you to write the best programs possible.


    You are a liBeral programmer.
    Programming is a complex task and you should use white space and comments as freely as possible to help simplify the task. We're not writing on paper anymore so we can take up as much room as we need.

    My comments on the results.

    Planner is completely right. If you read this blog regularly you'll know that I am an advocate of old-fashioned planning and through design before coding. That may make me a dinosaur but it worked for me my whole career.

    High level is true today but wasn't always true. There was a time when bit fiddling was a great joy for me. Setting flags, traversing lists (using pointer arithmetic) and low level coding were fun and interesting. As I've gotten older I really like to reuse code. I have been there, done that, and have no need to prove to anyone that I can "do it from scratch." Give me the blocks and I'll build you your tower!

    Solo situation? Yes, I guess so. But honestly I work fine on large multi-person projects. This happens because of the planning phase. As long as all the inputs and outputs are well defined there is no problem with people coding in something like isolation as long as everyone follows the specification. I like working on a piece of code that is small enough to keep in my head at one time. Until the program isn't broken down into manageable pieces so that individuals can work on them the planning isn't finished to me. That being said I have never given pairs programming a try on a real project. It is an idea I think I might like.

    No one who has read my posts on the value of commenting (like this one which started a lot of discussion in the comments - comments on comments?) will be surprised by me fitting into this definition of "liberal programmer." I like my code documented and "pretty." White space is your friend!

    What do you think about this test? Does it get you right?

     

    Technorati tags: ,
  • Computer Science Teacher - Thoughts and Information from Alfred Thompson

    The Prime Number Syndrome

    • 9 Comments

    Tucker Balch, a computing professor at Georgia Tech,  blames the decline in computer science students in part on what he calls the "prime number" syndrome. According to this AP article the Prime Number Syndrome is:

    It's the traditional way to teach computer science students by asking them to write programs that spit out prime numbers, the Fibonacci sequence or other mathematical series.

    In short part of the problem with computer science courses is that they are too much about the math. Students are not all interested in the math. That may be partially a result of computer science courses originating from math or engineering departments. A lot of the people in the early years of computer science came out of mathematical traditions. Math was/is interesting to them so that is how they teach computer science. Some of the problem today may be that not everyone thinks that calculating prime numbers is really that exciting. They are interested in a lot of other problems though.

    Some computer science departments are realizing this and are bringing other disciplines into the mix earlier in the program. At some places it is robotics. In some game development. In still others there is this new idea of "media computation" programs. There are a growing number of computational biology programs as well. These programs are all about getting students interested by expanding beyond just doing the math.

    Now at some point most computer science majors wind up needing more math classes. And there are a lot of concepts that computer scientists use that are related to mathematical concepts. But the days when we need to weed out students early by forcing them to fit the mold of pure math interests are long gone.

    A lot of high school computer science teachers also teach math these days. In fact in some states a math certification is required to teach computer science. I guess I was a rarity though. I'm never been a real mathematician and while I assigned the odd Fibonacci sequence a lot of the projects I came up with on went in other directions. I like the idea of the robotics curriculum they are developing at Georgia Tech. But I'm a robot sort of guy. I'm sure the media computation and bioengineering programs also attract a lot of fans. I tend to think that at the high school level, especially for a very first course, what you might want is a lot of variety. The more different disciplines that come into play the more likely you are to catch the interest of more students. And to me, getting students interested is a major goal of a first programming course.

     

    Technorati tags: ,
Page 1 of 8 (24 items) 12345»