Document your code. This is done by inserting comments. The computer ignores them but they are read by other programmers. Almost all serious programming languages allow comments. However, not everyone agrees on how many comments to write and what they should contain.

A common practice I have seen is to write program prologues. These are a collection of comments found at the very beginning of a source code module. Usually it documents: a copyright notice, the source code module name, a description, the date created, the author’s name and the revision history.

Each method can also have a prologue that documents: the method name, a description, the parameters and the return type. I have heard it said that these comments are not necessary since code is self-commenting. The argument goes that if the author chooses a descriptive name for a method and its parameters, then no comments are necessary. In practice this is never true. Don’t be that lazy and arrogant developer who needs a swift kick in the posterior.

It is possible to go overboard and document too much. The problem here is that as code changes you now have an additional task of maintaining the comments. A good rule of thumb is:

Comments should document the "why" not the "how"

For example if the developer choose to implement a splay tree he should not document the fact that it is a splay tree. Why? Because another developer may decide that a red-black tree performs better and replace the original implementation. Now the comment has to change, too. It is better to document things like hacks and decisions that maintaining developers should notice. For example, if there is a bug in the third party library you use to format a date, a workaround may be developed to fix it. A comment should be written to document the fact that the code has been written to work around the problem.

Remember that comments are written for humans. Be aware that other developers read them. Do you really want them to remember you as a foul mouthed crank? Think about that before vent your frustrations in your code comments. Just a thought.

I was thinking about the whiny outburst of former Winamp programmer Justin Frankel a few years ago. He started Nullsoft, made Winamp and then sold it to America Online (AOL) for $86 million. Then the renegade developer released a piece of file sharing software that was embarassing in light of the proposed AOL and Time Warner merger. When AOL did the corporately responsible thing by blocking the software. Frankel threw a fit. In his blog entry he states: “For me, coding is a form of self-expression” and “The company controls the most effective means of self-expression I have”. Boo hoo, poor millionaire! He did not get much sympathy from us professional developers.

So, I pondered these questions: Is coding really a form of self-expression? Can software engineers express themselves in code? Can programming be considered art?

Let me clear us something. Coding, or programming, is only one-fifth of the complete software engineering process. All of the steps are: design, programming, documenting, testing and maintaining.

I like to compare software engineering to building a car. Is car building art? The process of assembling a car can hardly be considered a form of self-expression.

There are certainly cars that people think are beautiful. But mechanics do not sit around with stacks of auto parts and try to make a Mustang. There usually is a design first. Also, most cars are safety tested. I think it is irresponsible to release software without testing it thoroughly. Why aren’t more software companies held responsible for the financial impacts that their buggy products cause? How is it we have come to expect computer software to fail? That is a discussion for another blog entry.

How does software get written? In the corporate world it starts with a business problem. For example a chain of Mexican restaurants might ask: “How many fajitas did I sell yesterday?” The initial step in software engineering is to identify the business problem and gather requirements. Then a design is developed. If a design is good, then the process of coding is almost mechanical. Of course, there are issues that arise that need creative solutions. I think the structure of software code and creative solutions to issues are the closest a coder really comes to self-expression.

So, can programming be art? No. Coding is best accomplished by a disciplined engineering approach rather as an art project. The resulting software can be admired and maybe even be considered art. But sitting at a computer and writing code is not a form of self-expression. That’s best saved for blog entry comments. Practice self-expression. Please post a comment.

Flavor Flav knows what time it is. He wears a clock around his neck to help.

A common problem I have encountered in software development and testing is clock synchronization. Internal computer clock time will drift to inaccurate values even when initially set accurately. PC clock circuits only cost a few cents to make and are notorious for becoming wrong over time.

This causes a variety of problems. Developers on Unix systems like to use the ‘make’ command. This command compiles new and modified code without having to recompile unchanged code. It uses the clock to deteremine which files need to be recompiled. If source code resides on a separate server and the clocks are not synchronized then the make program will not work correctly.

Another problem manifested by unsynchronized clocks is correlating test results. Imagine running a load test on system where the client, database server and application server all have different times. Someone trying to analyze the results of the test will go cross-eyed trying to examine critical events in the test. I have seen this problem at two different companies now.

A network time server should be used to keep every computer’s time in sync. The most used solution for clock synchronization is the Network Time Protocol (NTP). It utilizes a client/server architecture based on UDP message passing. Fortunately, it is also built into the latest versions of Windows and most Linux distributions.

In order to keep your clock in sync in Windows right-click on the date/time in the task-bar. Now click on ‘Adjust Date/Time’. Now click on the ‘Internet Time’ tab. Yeeeeaaaahhhh Booooyyyy!

An email arrived today from Amazon announcing the Amazon Mechanical Turk web service. It is named after a famous 19th century chess playing machine that turned out to really have a person inside.

Amazon touts the service as “Artificial” Artificial Intelligence. It works like this. A company may send trucks through a business district taking photos. They then need somebody to pick the best ones for a database of store images. In exchange for a couple cents a human can take a look at a few photos and select the one that best looks like a storefront.

Developers can use web services to submit tasks to the Amazon Mechanical Turk web site, approve completed tasks and incorporate the answers into their software applications. To the developer the application sends the request to the web service. In turn the service returns the result. Behind the scenes the results are the product of human input. Humans come to the web site, search for and complete tasks and receive payment for their work.

Got spare time? Earn a few cents.

This weekend I discussed potential web page designs for Atomic Squash with Jason. Our conversation reminded me of some slides I wrote for an advanced HTML class at work. Over the years I have seen many poorly designed websites. Web page authors, it seems, tend to make some of the same mistakes when first learning HTML.

The following is a list of elements of good and poor design.

Elements of Poor Design

• Avoid gaudy backgrounds. A simple color is better.
• Avoid unreadable text and background combinations. You know about what I am talking.
• Do not make “Under Construction” pages. It is best just not to show a page that does not have content.
• Avoid frames. They break bookmarks. Use a table or div tags for layout instead.

Elements of Good Design

• Make a site map. If you have a large collection of web pages, this is invaluable.
• The top of the page is the most valuable part. Put a navigation bar and the most important content there.
• Use footers. Footers provide a visual cue to the end of content.
• Use context. Avoid “Click Here”.
• Give file sizes for files over 100kb in size. This prepares the user for large downloads.

Dijkstra, a famous computer scientist, once said: “Computer science is no more about computers than astronomy is about telescopes.” Computer science deals with design principles, requirements analysis, implementation of hardware and software, documenting and testing solutions and maintaining production systems. As you can see programming is only a small part of what is involved.

An article I read earlier this year lamented the fact there have not been any notable innovations in technology in recent history. So I thought about what innovations are possible given today’s technology. The following is my list of computer science projects which are ripe for innovation and which interest me:

COMPUTER SCIENCE PROJECTS THAT INTEREST ME

1. Compiled Javascript

Javascript is an interpreted scripting language built in to most web browsers. Most interactive web pages utilize javascript to do things like validate input or dynamically change form elements. One of the weaknesses with javascript is that all of the comments are sent, too. For pages with large amounts of javascript this amounts to lots of wasted bandwidth. It should be possible to compile javascript into codes that can be run in a sandbox within the browser. The process of compilation would eliminate comments and distill the code into a compact collection of byte codes.

2. Wired Elvis

A computer science professor once wrote a program to algorithmically generated jazz riffs using a functional programming language. I’ve always wondered what rock and roll could sound like if it were generated by a computer. Lets put the core in Haskore.

3. Anonymous P2P Networking

Peer-to-Peer (P2P) networks have made headlines lately. A fundamental issue with today’s P2P networks is that once you connect to the network your IP address is publicly available. This makes you a target esp. since information about your data transfers are routing through super nodes. It is theoretically possible to anonymize connection information. Some work has been done lately about obfuscating routing using a concept known as onion routing. It is not easy but I think it is possible to anonymize all connection information including the IP address. The question becomes, is it possible to ensure successful transfer given an anonymous destination? I think it is as long as you have at least three trusted servers. I haven’t worked out in my head how to protect the servers against untrustworthy servers or servers colluding to “poison the well”.

4. Whipping the WIMP

We can been using the same windows-icon-mouse pointer paradigm since it was invented in the 1970s. But people are still intimidated by using computers. Lets face it speech is a more natural means of communication. Advances in voice recognition mean that computers understand us better than ever before. Isn’t time that we at least augmented our system software with voice and gesture recognition?

5. Morose Pointer

Alan Turing proposed a test in which a computer program tries to fool human testers into thinking that they are communicating with a human. Every year there is a contest in which competitors try to see who does their best to meet the Turing Test. I’d like to go step beyond this. Can a computer make you cry? Can we care enough about a computer program to feel emotion? The mind boggles.

6. Parallel Compiler

In college I did independent research in the area of parallel computing. The compilers available at the time were poor. The best available was a compiler that took the C programming language and did its best to parallelize the instructions. There were other compilers and languages but they were awkward and difficult to program. As multiple processor PCs appear on mainstream desktops, the question is: is it time for a new programming language? I believe it is time for a language and compiler that is designed around explicit parallelism.

Open source software developers need to give credit and respect to documentation developers. The hard work needed for technical documentation is underappreciated. Unfortunately, the prevelant attitude among software developers is to install a Wiki and depend on the good will of others to document their projects.

Wikis do not work for technical documentation. For technical documentation to be usable it must be clear, complete, correct and current. Wikis fail on all of these points.

:: CLEAR

Most technical documentation Wikis are a mess. They are an unorganized pile of articles that can duplicate or contradict each other. Most Wikis are unmanaged by anybody responsible enough to purge the junk and reorganize the entries. I lament the revert war that may follow anyone brave enough to attempt to the clean the mess up.

The ‘search’ feature of most Wikis is inadequate. Multiple words in a search phrase causes the search engine to lose its brain. If your phrase does not match the words of entries exactly, the search engine will not be able to find what you need. You often can have better luck with a Google search.

:: COMPLETE

Wiki zealots want documentation to be incomplete. They feel the best way to encourage participate is to post stubs. Stubs are woefully inadequate articles that are the Wiki equivalent of the “under construction” signs once popular on web pages. Remember those? Stubs are just as pointless.

:: CORRECT

Not too long ago Google announced a project to scan in books and make their digitized contents searchable. Why not? Books have been subjected to the scrutiny of an editorial review. The author’s name is prominently displayed on the book.

Software developers have their superstars such as Alan Cox and Linus Torvalds. Can you name a technical documentation author whose work is as respected? Technical documentation Wikis do not reward either editorial scrunity or correctness. In fact who wants their name associated with anything that can be changed so easily to be incorrect.

:: CURRENT

A neglected Wiki is not a good source of current documentation. In fact technical documentation in general usually trails the release of project software. I challenge open source developers to make technical documentation a part of a ‘release’. In other words a software project is not ready for release until its technical documentation is updated. I am frustrated by outdated documentation in projects like Gnome and Cloudscape.

:: WHAT TO DO

Open source projects must find a documentation maintainer. That person is a developer — a documentation developer — who is just as important as any developer actively working on source code. Consider her part of your team. Give her CVS privileges. Answer her questions quickly and in a friendly manner. Give her credit in your project documentation and on your project web site.

A documentation maintainer’s job is to handle document submissions. He ensures that your documentation is clear, complete, correct, current, and consistent. Also, users may find a bug but will complain that the manual is wrong. If he cannot explain a feature, it may be a usability problem with your interface.

Wikis suck for technical documentation. But with the right attitude and a serious commitment open source projects can have decent technical documentation.