3 posts tagged “programming”

Last night I was thinking about what I wanted to write for the next couple of posts and I came up with an idea. I am going to try and learn a new programming language every month and write what I learned from my experience with the new language. Recently, I have been reading more and more about niche programming languages and how they have been influencing other more popular languages such as Java. One of the most talked about being Erlang and how it is amazing for concurrent programming. Currently the language I am teaching myself is Eiffel and I'll be writing more about it in about a week or so. Aside from that I have a few other languages I was thinking about learning. My list right now is:

• Smalltalk
• Erlang
• Haskell
• Lisp / Scheme

As you can see right now I only have five languages that I plan on learning. Now I want to come to you and ask for suggestions on any other languages you think I should learn. I'd really like to see a discussion or posts about any other languages that you know or are learning yourselves.

    Am I the only person that seems to find many open source projects are sorely lacking in documentation? It seems that there are many projects out there that hardly even have a wiki to store any information about the project. For example, Apache Maven is notorious for having no documentation or (worse) inaccurate documentation throughout the project and its plug-ins. Its really a sad thing because Maven is such a great tool, but often times I have to spend an hour or two looking up why this won't work or why this plug-in is incompatible with with that jar etc... This lack of documentation is one of the reason much of the Java community still stays with Ant for their builds. It just takes too long to migrate a project's build over to Maven because you have to spend hours looking up how to do even basic things.

    I'm not bashing the developers though, its great that they are contributing so much to the open source community.  I can personally attest to not wanting to write documentation because my ego gets the best of me and it feels 'below' me or I just can't be bothered by writing 'stupid' documentation. Instead, I am just suggesting that we developers start realizing that documentation is not just the boring part of coding, but instead is an important piece of great software.

    I tend to break documentation down into two different categories: code documentation and user documentation. Code documentation is a place where many developers, including myself, have misconceptions or bad habits. There are a couple different things we need to think about when you are documenting your code. First, we need to remember that other people actually do read the code we write, and it is important to remember that when you comment code. Someone else IS going to read what you put there. We programmers are a lazy bunch and we don't like to write too many comments. This is a good thing actually, to quote an overused statement 'your code should document itself.' That quote comes with a clarification on what 'self documenting code' really means. It doesn't mean that you don't have to write any comments in your code. What it really means is that you should be writing code that isn't so overly complex that it needs comments to explain what it is doing. Instead, much of your code should be simple and straight forward. This allows you to reserve the comments for when you do have to write some complicated code or you made a major design decision in your code.
   
    One nice thing about code documentation is that it grows with your project. As you change your code, you change your comments so stay in sync with what it is doing. Documentation that is out of sync with the code is one major problem about documentation that can be solved easily with an automated development process. As all projects should be doing continuous builds, the documentation can be put together and deployed in each nightly build. Maven does this, it wouldn't be hard to do this with Cruise Control or a simple Ant script that you have set up as a cron job. By just spending a few minutes and setting up a build cycle, you don't have to worry about making sure your documentation is up to date. Now isn't that what lazy programmers like us like to hear? I know I do.

    My second classification for documentation is the user documentation. This kind of documentation is designed for the end user, not us programmers. The people who use the piece of software every day will want to read this to understand what they can do with the program as well as where to start or how to fix a problem they encounter. This kind of documentation is the most neglected kind in many open source projects I find. Maven is really bad with this. There have been many times I will need to add something to my Maven build and I spend the next two hours finding out how to get it working because the documentation either wasn't there, or barely covered how to use the damn thing.

     Fortunately, there is at least some automation for this kind of documentation as well. While reading The Pragmatic Programmer: From Journeyman to Master, I came across their section on documentation. They suggest you do this documentation in a markup language such as DocBook so that you can generate many different formats of document from TeX, RTF, HTML, PostScript, etc. This way you don't have to repeat yourself, but you can format the documents in many different formats. User documentation should be just as important as documenting your code. It should not be an afterthought, but instead a first class citizen of your development process. Many projects would have much more success if they were properly documented, for example Apache Maven 2 would have a much greater adoption rate if there was documentation on how to use it! Sure, the mailing list is great, but I shouldn't have to go to the mailing list just to find out how to accomplish what should be a simple task.

    In conclusion, I have found that every successful open or closed source application comes with excellent documentation. Although it may feel like it is less important that actually writing code, it isn't. It makes you think about what you are doing and also helps others know what the thought process was. When you write good documentation, you allow the project to continue with new people and you allow the users to actually learn what they can do with your software. I propose that projects, large and small, should really take a moment to look at their development life cycle and see where they documentation comes in. If your project lacks in a standard way of documenting your code and project, you should sit down and work out a plan to include this in the process. Once you get this process down, you will really see the benefits of accurate documentation, both from the development end to the user end. Happy writing!