Programs are not created by just piling lines of code and processing them though a compiler. Real-life Software Development is much more complicated than this. This is not any news.
Sometimes, I have my friends asking me what tools I use to assist software development. Although for some it might be unacceptable to develop anything without the help of some tools, like a Version Control System or a Bug Tracker, for others these names have little meaning.
Here is a list of the most important tools available for software development, what are they built for and how can they help you. In this post I'll cover Version Control Systems and Documentation.
A Version control system, VCS, RCS or SCM for short, is a file repository where you leave your source code. But it does much more than just hold your files while you tie your shoes. A VCS enables many developers to work concurrently on the same project, merging each other's changes with yours. It also allows you to have acces to the state of your development on any time in the past, allowing you to check and fix bugs based on older versions. It is also possible to branch the development of the project and tag particular revisions. Also a deleted file is never lost forever if stored in a VCS.
There are so many benefits from using a VCS that, for most people, after using for the first time it becames inadmissible to start any other project without using it. Some put their whole home directories under version control.
The most common open-source version control software used today are CVS and Subversion. CVS is older and widely used, but has many problems that are inherent of its design. Subversion is newer but yet very mature, with almost all the features of CVS and almost none of its bugs. There are other software available, and also a comparison between various VCS.
The problem with documentation is that programming is very exciting, while documenting is very boring. But without a good documentation, even the most wonderful software becomes useless.
Like if it wasn't enough, programmers usually don't have just a single problem with documentation, but instead, a pair of problems: external and internal documentation. External documentation is the end-users manual, while internal documentation lists the pourpose of each and every module, function, variable, class (or data type), method and attribute that is be found on the source code. For each of them, there are many tools available that may simplify (or complicate) the task.
For external documentation, I use Docbook, which is an XML/SGML source document format that allows you to generate final documents in many different formats. It has a very steep learning curve, but the final result is very good. A Wiki can also be used for maintaining documentation more dynamically, but I'll talk about it later.
For internal documentation, you have Javadoc which is used by many Java programmers. There is nothing wrong with Javadoc, but people usually don't know the other choices available. Since Javadoc is specific for Java, if you use a different language, you have to look for a different documentation tool. My choice is Doxygen, which has plenty of features, supports many languages (including Java) and allows you to use a syntax similar to Javadoc if you want.
On a next post, I'll talk about bug trackers and wikis.