5

I have multiple projects that I am involved in, and for one of those I have worked for 2 years and delivered a piece of software that is being used in production at customer site.

Everything went really great and customer got back several months after the initial release and said that they want to make some modifications. This is often some new features they would like to have, but sometimes it is also about changing the UI and making changes in the business logic used for data management and visualization.

After this release, they are happy using the software. I keep working in other projects occasionally providing them with the support and guiding on best practices, just a couple of hours every month.

After 1 year since the release, they got back with new feature requests. As I haven't been working with the code base, it took me a couple of weeks to get into the details of implementation, bury into the code, consult internal documentation etc to catch up on what we did, how we did, and why we did it. As there is some jargon used, I need to read through the docs just to recall the terms being used.

And then after 1 year since the latest release, they got back with new feature requests. The cycle repeats. Basically this could be illustrated with this time line:

  • Jan - new feature requests coming;
  • Jan - Feb - developing new features, releasing, fixing bugs;
  • Mar - Dec - don't touch the code base at all;
  • Jan next year - new feature requests coming.

Obviously, this initial "getting-ready" time is something I want to keep as low as possible. I also have concerns on how to approach the customer with this information, because the 4th / 5th part of the total working time is spent on catching up what was done etc rather on building new features.

What are the best practices and how to deal with this situation when one gets new feature requests for the software that one doesn't develop continuously and new feature requests coming after releases with 8-12 months intervals?

  • 2
    Do you have unit tests ? – Spotted Nov 2 '16 at 12:30
  • @Spotted, yes, I do. They together with some regression test suites are of great help to see how the program is supposed to be used, so I don't need to re-learn it. But still, I just feel being so unproductive and it takes time to get back to the project. – Alex Tereshenkov Nov 2 '16 at 12:34
  • Do you have a glossary for domain-specific terms ? – Spotted Nov 2 '16 at 12:53
  • Keep your project as clean as possible. Remove unused parts or half baked code and documents. This way next time you come to study the project you won't waste your time understanding things that are not in the project any more. – Afshar Mohebbi Nov 2 '16 at 12:59
  • @Spotted, yes I do. – Alex Tereshenkov Nov 2 '16 at 14:06
9

Even if you are working continuously on a project, unless the project is tiny, you'll have to switch between features, some of which you haven't modified for months or years.

And if you work in a team, chances are you will constantly discover parts of the code base you haven't written in the first place.

So what makes it possible to reduce the time wasted rediscovering the project?

  • Refactoring. This is the most important technique which will allow you to spend less time asking yourself what was you thinking about when you wrote a piece of code two years ago.

    It is not unusual, when developing a new feature, to try ideas, and to care less about architecture and design, simply because requirements may be unstable, and you may not be sure how the requirements should be implemented. However, once the feature is implemented, the work is not done. With the help of regression tests, come back and refactor the code. Regularly.

    As explained by DocBrown, by being refactored regularly, your code will become self-explanatory, which has a huge benefit when coming back to the project in a few years: instead of constantly switching between code and documentation, you'll be able—ideally—to simply follow the code. If you also follow the five principles of SOLID, then it would become much easier to bring changes later: sometimes, you'll simply be able to create a new class for a new feature, without even touching to the existing code. In other cases, you'll need to modify the existing code, but you'll know that the changes will be limited to one or few classes, with little risk of creating regressions somewhere else.

  • Architecture and design. Do you have one? (It seems from your question that you do) If not, it will be difficult from the code to get a larger picture; thus, understanding will suffer.

  • Style. Coding standards matter because they make it easier to read the code. As explained by DocBrown in his excellent comment:

    A class naming standard can help to find the correct class to change more easily. A naming convention for making a distinction between local and non-local variables makes it easier to understand the impact of a planned change. Moreover, exploring an existing project involves lots of code reading, so everything which makes the code easier to read will speed up the process.

    Given that it is usually very easy to enforce a common coding standard by using an existent standard and enforcing it automatically in the pre-commit hook, there are no excuses not to use one.

  • Documentation. You don't need to write a one hundred pages document explaining everything in detail: it will be boring, and you won't enjoy reading it. However, a few diagrams would provide a tremendous help later. Documenting different choices is a good idea too: for instance, if you decided to write your own thing instead of using something which exists already, explain why you did so: maybe third-party solutions were incompatible with the system, or too slow, or had some severe limitations.

  • The list of terms. Quoting from your question:

    As there is some jargon used, I need to read through the docs just to recall the terms being used.

    In some projects with a lot of technical (or domain) terms, I was actually creating a list of terms. The goal is then to ensure that you update this list regularly, and that you use those terms consistently.

    The list should be as affordable as possible. If it's not easy to read, you (and your pairs) won't use it. If it's difficult to modify, it will quickly become outdated. Note that it takes time and practice to get a format which will suit you.

Note that whatever you do, you will spend some time understanding the code two years later, even if it is the code you've written yourself. Look at open source projects: some are written by talented developers who do a great job, but even then you'll spend a few hours to a few days exploring the project before you can contribute to it. Your code is not different: you can't remember every detail for years, which means that when coming back to your project a few years later, you find yourself in the same situation as if the project was done by someone else. Moreover, your style may have changed; you've learned new tools, language features and APIs, which could only widen the gap between you today and you two years ago.

it took me a couple of weeks to get into the details of implementation

Depending on the project size and your meaning of details of implementation, spending a couple of weeks may not be exceptional; if it takes four hours to develop a feature for your customer, and you ask to pay for a couple of weeks and four hours, things may go wrong. Make sure you learn about your project only things you need to know in order to implement the feature.

For instance, if the product is an e-commerce website, and the feature is a change in the way PDF invoices are generated once a user bought something, there is only a tiny part of the project you need to understand. You don't have to know, for instance, how products are displayed on the website, or how cart works. Unless it's a legacy spaghetti codebase, your changes will only affect the code which deals with PDF generation of invoices, and won't propagate to other parts of the product.

  • brilliant, thanks a ton. Good point on the list of terms - I actually have 2 pages Word doc with the terms explained, helps a lot. Good to know I am not alone on this :) Thanks for the illustrations and analogies, they are of tremendous help. Refactoring seems to be always hard to me as it is often easy to break things (even when having decent unit and regression tests)... I will wait a couple of days and if no one else posted something "better" (I doubt it is possible), I'll accept your answer. – Alex Tereshenkov Nov 2 '16 at 12:45
  • 3
    Not sure if it may help as much as the things you have enlisted, but I would suggest also a change log. This kind of documentation offers a very summarized overview of the project and it takes just few minutes to read it. Happens to me that often I don't remember why I did what I did, change log helps me to contextualize the changes and the actual status of the project – Laiv Nov 2 '16 at 12:45
  • 2
    Good answer. I suggest to add the obvious "coding standards and conventions". That will help to reduce the need for documentation a little bit. And just "Refactoring" does not improve the code automatically, the thing I miss in this answer is a clear statement that the refactoring should be done with the goal to make the code more self-explanatory and SOLID. – Doc Brown Nov 2 '16 at 19:04
  • 1
    @DocBrown: I thought about style and coding standards, but decided not to include it, because I would imagine that it's not such a big deal (including even the uniformity itself) when rediscovering the project. Style inconsistency makes the code difficult to maintain, but shouldn't influence too much the way someone explores the project. What's your opinion on that? – Arseni Mourzenko Nov 2 '16 at 20:49
  • 1
    @ArseniMourzenko: it depends how consistent or inconsistent one's coding style is. For example, a class naming standard can help to find the correct class to change more easily. A naming convention for making a distinction between local and non-local variables makes it easier to understand the impact of a planned change. Moreover, exploring an existing project involves lots of code reading, so everything which makes the code easier to read will speed up the process. – Doc Brown Nov 2 '16 at 21:41
0

Alex, try to talk with your customer why they come with requests each January.

Probably they have some money for improvements in the budget each year and they spend all of them right away at the start. However it is obvious that for the rest of the year they have to sit and wait (loose money not getting improvements).

It means that the budget they have is too small and you can try to help with business case to increase it. Take features from the last year and calculate in real money how much it costs for the company not to have them per month, how much they lost including your re-learning costs. Explain that it is more beneficial to order more/out of the budget rather then wait for the next year. It can solve your issue since you will have more job to do and bring some profit.

  • Good point, thank you, Vlad. It seems that they want to order in bulk and then get a single release and do all the testing in a single transaction instead of me shipping often and them testing/accepting small chunks. This may change in the future, though. Thanks again for the description of money conversion, excellent. – Alex Tereshenkov Nov 2 '16 at 12:50
  • Alex, I'm not sure if you get my point. It is not about bulk vs iterations. It is about the fact that amount of work you receive is probably limited by their budget. If you can help them increase the budget you would get more work and less time between releases => problem solved. Would it be 1 release per 4 months or the big one for 8 months is a different aspect yet to be encountered by you. – Vlad Nov 2 '16 at 13:12
  • Ah, OK, I got you now :) increasing the customer budget is never a bad idea ;) provided you can do that... – Alex Tereshenkov Nov 2 '16 at 14:06

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.