If you’ve been coding for a while, you probably have heard of the importance of ”preparing for maintenance”. Especially if you very seldom are on the ”maintenance end” of things. But you probably have (at-least) two questions; 1) Why?, and 2) How?
The ”why” I will only touch very briefly, this has been written about in great extents ever since the first program was written (well, almost anyway). I will instead focus on the ”how”. This seems to be a bit harder to find info about.
Why?
The software life-cycle isn’t as short as a lot of people seem to think. Mostly the ”sexy” end of things are requirements, design and construction (programming). Most people don’t like to think about testing and maintenance (IMHO). (And I will not really touch on the testing-subject in this article…not because it’s not sexy, but because this is not the focus this time. 
)
The cost of maintenance has been estimated at 50% of total life cycle costs ([VV00] [AA11]). Just think about it; you develop a new system for lets say one year. How long will it live? 5 years? 10 years? Or maybe 20 years…? A system is very rarely replaced, just look at the Y2K-bug. During this time a lot of things will happen. New requirements, new operating systems, new hardware, new integration’s, new millennial etc.
To read more about the ”why”, and to get some more hard facts, looks at some of the references/links below this article.
(Actually, maintenance is not only for fixing bugs. Coding because of new requirements is about 80% of all maintenance ([AH93] [Pre97] [Pig97]))
How?
So, now we know that maintenance is good to prepare for! But how do we do this?
There are several answers to this, I will touch the things I think are important in concern with time and budget at the time of development. These might not be a 100% fit for you, but should be a good starting point I think. (Note that this is a personal opinion based on my own, and others, experiences)
Documentation
This seems quite obvious. Unfortunately it is not always.
Getting a system with ”good” documentation isn’t as easy as one might think. Could be lack of time, budget or know-how. Or just pure laziness.
So, what is ”good” documentation. According to me it should be a ”brief” explanation of the system. Not too detailed, because then you would have to update it for almost everything new you do to the code. And nobody would read it because it’s too thick… But it should be enough for a junior developer, who has absolutely no knowledge of the system, to have a good understanding of what the system does.
The documentation should include (NOTE It doesn’t have to be in one document, could be several documents):
- Why was the system developed (”Explaining the business purpose of the app”)
- For whom (”Client”)
- Users (who are they, what do they want)
- What it does
(the four parts above should not be more than 1 page in total)
- Some architectural info/thoughts about the system, patterns followed etc
- Some functional info about the system (these pages are available, you can do this on that page etc)
- Use cases (if they exist, keep them in the documentation)
- Integrations (do we get data from some other place/s? do other systems use this system? etc)
- Environment requirements (OS, 3rd party software etc)
- How to set up a developer environment (step-by-step, from scratch to build, ”don’t forget to bazugle the bazigle or else the dangwham won’t work”, instructions on how to get the project to compile (aka the F5 experience), etc)
- How to deploy (to Acceptance/Staging/Production…could be as easy as ”1) Build – 2) Deploy” but more often it is more complex as ”Step 1….Step 76: Deploy”)
- Configurations you have to make (for different environments – what, why, how)
(the parts above could basically be very large, but you should make it as short and concise as possible or else it will not be read or updated)
Test
To make sure that a fix doesn’t break anything, the following is very nice to have also. Especially for a new dev that doesn’t quite know everything about the system yet.
- Unit tests
- Regression tests
- Test cases
Code
I wont delve on this, you know how to code. But still, comment where necessary, but don’t comment too much.
Check in (you of-course use some kind of versioning system) 3rd-party software that you use, if possible. Years later it can be a real pain to find… If you have the source code also, even better!
Done
Put yourself in the junior developers shoes. What would you have liked to have known about this/a system that you know absolutely nothing about? You could save major hair loss for a fellow developer! (speaking from my own experience…)
One of the challenges is to keep the documentation alive as time goes by. Make sure to have a plan for this (inform new devs, make it a check-point to do before an issue can be closed, when estimating time for an issue – include time for documentation etc).
If you are on the receiving end (maintenance), make sure that you don’t accept delivery until you get all things above (well…you could always dream).
And again, keep the documentation short and brief!
References / Links
[VV00]: NIESSINK, F. AND VAN VLIET, H. 2000. Software maintenance from a service
perspective. Journal of Software Maintenance and Evolution : Research and Practice 12,
103-120.
[AA11] Araújo , R. Adriano, S. Oliveira, L.I. (2011) Hybrid morphological methodology for software development cost estimation, Informatics Center, Federal University of Pernambuco, Recife, PE, Brazil
[AH93]: A. Abran and H. Nguyenkim, “Measurement of the
Maintenance Process from a Demand-Based Perspective,”
Journal of Software Maintenance: Research and Practice,
Vol 5, no 2, 1993 [pp63-90].
[Pre97]: R.S. Pressman. Software Engineering: A
Practitioner’s Approach. McGraw-Hill, fourth edition,
1997. [c27s27.2.1-2]
[Pig97]: T.M. Pigoski. Practical Software Maintenance:
Best Practices for Managing your Software Investment.
Wiley, 1997.
http://www.scribd.com/doc/76129139/Pigoski-Practical-Software-Maintenance-Best-Practices-for-Managing-Your-Software-Investment
[SWEDISH: Webbapplikationer, från fristående kod till implementering av ett ramverk (Mårten Nilsson, Sep 25, 2012)]
https://gupea.ub.gu.se/handle/2077/30409
[Software Maintenance As Part of the Software Life Cycle (Kagan Erdil et al, Dec 16, 2003)]
http://hepguru.com/maintenance/Final_121603_v6.pdf
[Software Maintenance, chapter 6 (Thomas M. Pigoski, May 2001)]
http://sce.uhcl.edu/helm/SWEBOK_IEEE/data/swebok_chapter_06.pdf
[ISO/IEC 14764:2006 - Software Engineering -- Software Life Cycle Processes -- Maintenance]
http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=39064
[Wikipedia on Software maintenance]
https://en.wikipedia.org/wiki/Software_maintenance
