Is it realistic to deal with a huge undocumented code base for master's project?

Question

I'm currently pursuing a Master's degree in a STEM field and working on a thesis. For my master's thesis, my advisor suggested I expand the code of the group's software and add new features to it. However, is very large (some files are thousands of lines long) and hard to read. It consists of many different files and there are hardly any comments that explain what the functions do, the meaning of the variables, etc. There's no documentation that explains what the functions/classes do. It seems like whenever I am focusing on what a function does, there's multiple functions/variables in it that are defined in another file and those functions/classes themselves are hundreds of lines long

While my advisor has mentioned he is open to helping me with whatever questions I have, most of the problems I'm having are related to the code, since it's so gigantic and I don't even know where to begin to ask questions. But the prof doesn't know much about the code, so I have to ask the postdoc whenever I have questions about the code. However, the postdoc doesn't even know alot of the code (he knows c++, but most of the code was written by a former postdoc), and told me I should email that former postdoc to answer my questions about the code.

I've spoken to some people about this, and they've said this is a very bad situation. Should I leave this group and join a new one, even if it means I have to delay my graduation by an extra semester(assuming that I will graduate on-time if I continue with this current group)?

It's been a month since I joined this group and I hope to finish by next spring, but I don't know how realistic that goal is.

Answer 1

I would be very wary of taking on this thesis topic. There's a huge amount of programming effort here, but you're not trying to get an MS in software engineering, so this will necessarily be a project in which you spend most of your time doing work that is actually outside of your discipline. Furthermore, there's a risk that either you'll never be able to understand various aspects of the code or that you'll misunderstand things and then make changes that break the code.

Answer 2

This isn't a complete answer by any means and this is very far from being my field, but I wonder if there's a possibility of an alternative before you jump ship. Could go to the existing postdoc and ask him if there is any project related to the code base, that you could do in the time available, that would help move his work forward? Then take that idea back to the supervisor, saying that you've talked it over with the postdoc. You might get a bit of informal supervision and you could work on a portion of the code that you could be advised on...if it was technically possible, everyone was amenable etc.

Answer 3

sorry to hear about the difficulties. I used to be a graduate student too and most of my current friends who I interact with almost daily are graduate students. As Greg pointed out, this scenario is very common but certainly far from ideal. I understand your concerns very well since I was in this scenario not too long ago. I was debugging a code written by a earlier post-doc which was in C++ and I was only a novice at C++. My supervisor knew that I was a novice at it and he did not know much about the nitty-gritties of the code. However, I was only debugging the code so did not need enough expertise to add new features. In the end after a couple months of effort I was able to fix the code. That was my story.

However, in your case there are 4 possibilities:

1) Your supervisor envisions some useful features but has no idea how much effort it is to implement it or thinks it may not require much effort but in reality it does. - (Bad scenario)

2) Your supervisor has somewhat of a good idea of how much effort it is and needs you to do it so that you could use these new features in your work (to follow) and write up a thesis based on it. - (Not a bad scenario unless you have your own different likings for topics you want to work on for your thesis).

3) Your supervisor has somewhat of a good idea of how much effort it is and needs you to do it just as something useful for the group besides your thesis. -(Not a bad scenario unless it takes more than a month or two and absolutely can't go in your thesis).

4) Your supervisor has somewhat of a good idea of how much effort it is and needs you to do it because it will be useful for the group and it is going to take several months and does not help you advance in your field or cannot go in your thesis. -(Bad scenario)

Now, you need to figure out which scenario you fit in broadly. The way to figure out is to discuss and ask questions to the post-doc in the group as well as your supervisor. Ask for a meeting and discuss your concerns (perceived as not the best thing to do- but in reality it is indeed the best thing to do). Many students worry about their supervisors judging them negatively. This worry needs to be suspended since something greater is at stake. Proper communication will eventually lead to good results and in turn a good judgement anyway. Again, you need to discuss and understand how useful this project is for yourself. Then you need to come to a consensus wit others about how long it is expected to take and if it is worth your time to do it. Lastly you should also discuss and put some safeguards in your plan, i.e. a timeline where you expect smaller goals of the project to be completed and if it does not work out the way you want what will be plan B?

And another important thing: If the project or other possible projects that you could take up in this research group do not interest you at all, then you should look elsewhere.

Hope this helps. My best wishes. Feel free to ask more questions in response.

Answer 4

Because I know some people here may not be completely familiar with computer science and "documentation", I'm including this to help people get a better grasp on the scenario.

The Context

Somewhere in life, if you work with code, regardless of whether you enter research or industry, you are likely to come across magic code.

In most cases, the magic code works. No one knows how or why, and the original magician developer has likely moved on. So we have a product that works, but no one knows the incantations methodology that was used to produce the results.

An example of magic code:

c=["6B8CFF","B13425","6A6B04","E39D25"];a='0155000555540ABEC02EFEFC2EBFBF2BFEA803FFF00A6A002A69A8AA55AAF9D76FFD557FF5555F0541502A00A8AA00AA';with(document)for(i=0;i<96;write('<br>')){h=('000'+parseInt(a.slice(i,i+=6),16).toString(4)).slice(-12);for(j=0;j<12;write('<rp style="padding:1 8;background:#'+c[h[j++]]+'"></rp>'))

No one, not even people with knowledge of this language, will instinctively know what this snippet of JavaScript does. It draws a picture of Mario

Writing code like this, the developer will know what they're doing, but no one else will. It is a remarkably efficient time and space-saving technique if you don't have to explain to anyone what you're doing.

The caveat about uncommented code is that somewhere down the line it falls apart and becomes impossible to improve or understand. Someone before you most likely took the code and coded on top of original uncommented code, and kept kicking the documentation down the line for someone else to handle, i.e. saved time now for an eventual time cost later.

At this point, it sounds like the "later" has reached critical mass, where progress cannot continue unless previous progress has been documented.

Leaving the project removes you from the problem, but the problem still exists, and will land in someone else's lap, and if the code is as bad as you indicate, this is application is on development death's door.

What you should do about it

You should meet with your advisor to discuss your concerns, as well as these issues:

• This code, while functional, does not follow standard coding convention, and will likely need to be brought up to standards before development can continue.
• Documenting of undocumented code is time-intensive, but ultimately improves future developments Documentation can easily take a fair percentage of the actual time spent coding. If this code has been developed for 4 years, I wouldn't find it unreasonable for a new person to take several months to document everything, or a few weeks to document the important stuff, while leaving the guts intact.
• Possible alternative projects such as retrospective analysis and improvement of the application for improvements, while corrolating your actual topic with how it is being handled by the code.

Answer 5

The short answer to your question is, yes, it is realistic in the sense that it is a common scenario, and no, it is not realistic in the sense that it can seriously hurt your career and you may not want to get involved in a quagmire like this.

The long answer: scientists are notoriously bad in developing and managing codes. As a result, you often end up like 30 years old undocumented FORTRAN codes that run only a Win95 machine. It may sound exaggeration, but I used to have an old PC because certain software could only be compiled with certain Fortran compiler which has last version running only Win95 or older systems. The situation therefore common and obviously it can be very tiresome to fix all this. If you don't think it worth the effort, don't get into it. On the other hand there are cases when the code can do magic and important magic. In this case it is an opportunity to you to became a magician and an expert in a tool that needed by many, but for obvious reasons, can be used by only very few. In other word, if it is an important program, it may pay of on the long term.