Saturday, February 1, 2014

Making life easier for future software archaeologists

Yesterday I went to "The First International Conference on Software Archaeology" run by Robert Chatley and Duncan McGregor - it was excellent. There were "lightning talks" run by Tim Mackinnon - here is a blog version of my talk.

Intro

If you have worked on a piece of software that is running in production, but hasn't been changed for a while, you may have had to do some software archaeology to work out how to make changes to it.

In this article, I list some problems that I've encountered when doing software archaeology, and some suggestions for making life easier for future software archaeologists.

My suggestions are not always applicable - but please consider them carefully. It is valuable to your client to make it easier for future software archaeologists to work with your systems. If your systems are any good they will probably be used for much longer than you think.

Where's the source?

Sometimes source code is lost (e.g. because of a VCS migration and some repositories don't get converted because nobody thinks they are needed any more). For Java projects there is a simple way to avoid losing the source code - include the source in your binary jars.

Where is the documentation?

Although it is possible that the source code will be lost, more commonly, source code repositories do survive. However, documentation systems (for example wikis) are likely to be decommissioned sooner.

Even if a documentation system isn't decommissioned, the information related to old projects can get deleted, become out of date or inconsistent with the version actually running.

In order to keep documentation consistent with the system, please commit it to the same VCS repository as the code. Depending on the VCS system used, you might be able to serve documentation to users directly from your source control system.

Where are the dependencies?

Sometimes artifact repositories are decommissioned. For Java projects, instead of using an artifact repository and ivy/maven/gradle etc, commit your dependencies into a "lib" folder and refer to them there. I know this is very controversial approach - it goes against current trends, but is actually a very practical approach. It is likely that the source code repository will outlive the artifact repository.

How do I build the software?

Sometimes build tools go out of fashion and it is difficult to set up a working build for archaeological code. Therefore, at the very least, include instructions about how to build the code in the VCS repository. Even better for the future archaeologist, commit the build tools and any setup scripts.

How do I work on the software?

In addition to being able to build the software, there may be development tools needed to work on it. For example, if the software is partially generated by some (usually hideous) tool. In such cases, some of the source code isn't really what the developer works on (e.g. GUI builder generated code).

Include (at the very least) instructions for how to set up a suitable development environment. Even better, commit the development tools and any setup scripts.

How do I run the code in the production environment?

For a large system, it can be difficult to work out how the production servers are meant to be set up. Therefore, include instructions, or even better, scripts (like Puppet or Chef), for setting up any servers etc.

How did it get to be like it is?

When looking at an old system, can be useful to see the history of decisions about how a system got to be like it is. It can be useful to have a changelog checked into the source code repository. In my lightning talk, Nat Pryce said that for a home project, he committed the complete bug tracker system; that could be very useful for a future archaeologist.

In conclusion

Fashions change (e.g. tools become obsolete), reorganizations happen and systems get migrated (and sometimes things get lost in the process). If you want to do the best for your client, remember that successful software can last a really long time, so you should leave better clues for future software archaeologists.

Copyright © 2014 Ivan Moore

15 comments:

Nat Pryce said...

The issue tracker I wrote that stores its state in the version control repository is Deft: https://github.com/npryce/deft

Admin said...
This comment has been removed by a blog administrator.
momimi said...

Resultangka88
Resultangka88
Resultangka88
Resultangka88
Resultangka88

PMP Certification said...

On the off chance that your searching for Online Illinois tag sticker reestablishments, at that point you have need to go to the privilege place.We offer the quickest Illinois tag sticker restorations in the state.

360DigiTMG PMP Certification

360DigiTMGMY said...

Especially superb!!! Exactly when I search for this I found this webpage at the top of every single online diary in web crawler.
hrdf claimable training

dataanalyticscourse said...

I really like your writing style, great date, thank you for posting.
Data Analytics Course

tejaswini said...


wonderful bLog! its intriguing. thankful to you for sharing.
pmp certification in malaysia

devika iangar said...

Set aside my effort to peruse all the remarks, however I truly delighted in the article. It's consistently pleasant when you can not exclusively be educated, yet in addition, engaged!
HRDF Claimable

360DigiTMG said...

I think this is the minimum value to earn more than just commit
hrdf contribution

Togel online said...

Cara Main Colok Naga Di Situs Bandar Togel Online Terpercaya

360DigiTMGNoida said...

Phenomenal post.I need to thank you for this enlightening read, I truly value sharing this incredible post.Keep up your work
data science courses in noida

Ramal4D said...

Judi Togel Online merupakan permainan menebak angka atau nomor melalui situs resmi disetiap pasaran togel yang buka. Pasar togel online yang kami sediakan ada 10 antara lain : Miami, Hk Siang, Sydney, Sgp, Sgp45, Malaysia, Almada, Qatar, Hongkong, Espana. Menyediakan juga prediksi togel online

PMP Certification said...


Somebody Sometimes with visits your blog normally and prescribed it as far as I can tell to peruse too.
https://360digitmg.com/course/certification-program-in-cyber-security-analytics

360digitmg said...

Wow what a Great Information about World Day its exceptionally pleasant educational post. a debt of gratitude is in order for the post.
business analytics course

PMP Certification said...

I really like your writing style, great date, thank you for posting.
360DigiTMG PMP Course in Malaysia