Making Software Go From Scratch
- Reading the Documentation
- Running the Software
- Building Software
- Conclusion
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
It would be great to take it easy on your first day on a new job or a new project, but you have a major headache looming in front of you. You get the same headache when you download the code from an open source project.
Here's the headache's name: Where do you begin?
A programming project is like a ball of string. Or more likely, a ball of several strings, with an undetermined number of ends. This article provides a few tips on how to unravel the string(s), and hopefully reach the end(s) you need.
If you're lucky, there's somebody around to show you the ropes. (Pardon the rapid shift in metaphor.) But that's not always possible. If you're maintaining a piece of commercial software, there will likely be other people on the project who can give you a clue. If you're really lucky, you get to talk to the original developer or the last maintenance programmer to get a brain dump of what he or she was thinking: what the program should do, what it actually does, and what direction it was going.
Much of the time, however, you won't be so lucky. Open source projects are especially tricky, since it's nobody job to give you that information. The source originators have never heard of you, and you probably can't get any face time with them, since they may be located in a completely different country. You can try USENET newsgroups or SourceForge forums, but it may take quite some time to get the information you need, especially for a lightly maintained project.
Reading the Documentation
The first place to look is always in the documentation. I've found that README files usually contain information related to the state of the project: recent bug fixes, new features, etc. Unfortunately, that doesn't tell you what the thing is really for.
The Javadoc can be very useful as a guide to the code, although it's usually light on how to use the code. Some programs include examples in the Javadoc, but that's a lot of trouble, since you have to do a lot of HTML formatting by hand in the code, which is tedious and error-prone. Since you have the source code, you can re-create the Javadoc. (I'm assuming that you're maintaining from the source. Maintenance without the source is possible, but that goes beyond heroics to comic-book superheroism, the stuff of water-cooler legends.)
Next, try poking around for files whose names end in .txt, .pdf, .htm, .html, and .doc. Occasionally you'll find good stuff in .info, .man, .ps, and .tex files, but those are less likely, and they require some specialized skill to read if you don't have the appropriate tools at hand.
The best place to start looking is a doc or docs subdirectory in the project's root directory. If the previous maintainers' computers are still around, try their desktops, home directories, and My Documents folders.
Of course, the more and effort time you need to spend in looking around, the more likely it is that you're better off just running the thing and trying to figure out from there what it does and doesn't do.