Refactoring previous intern's noodle code with future interns in mind

Question

Background

I've run across this problem as I am currently an intern at a large company's local software division. I have been given the task of extending a project that several previous interns have worked on (not collectively but sequentially). The project is written in C# and is a relatively simple tool (codebase of about 10,000 lines)

The problem

The first intern started writing the tool using pretty much only lists and ignoring the fact that setting up data structures (such as objects) makes the tool much more extensible and readable. The interns that came afterward did not bother to change this and instead built upon the tool in the same manner. This led to a couple of massive methods ( +700 lines), lots of global variables (most variables were global), and just very bad organization.

My Approach

I spent countless hours in the debugger understanding the logic of the code and have (for the most part) a very good outlook on it. I have written the required data structures and am organizing as well as rewriting "black box" portions of the code in order to make it possible to add a new feature without spending +2 weeks trying to figure out what is going on. I am doing this not just for my own sanity but for the intern that will come after me. I am constantly trying to focus on readability and simplicity while avoiding solutions that are short, effective, but slightly esoteric to another intern. I am following general OOP design and trying to avoid pitfalls that come from blindly believing a certain method is the best method without researching it and understanding why and how its applied. I am leaning heavily to a top-down approach in terms of design and how the execution flow will be laid out as this seems to be easier for others to quickly understand and internalize, but am open to suggestions for alternative approaches or methodologies.

The Question

How would I go about balancing my wish to write good code and writing code is understandable to a relatively untrained intern (the assumption is that they are pursuing a computer science degree but are still in school) while having a good outlook for the future in terms of extendability?

Any help is greatly appreciated

Answer 1

There are two things of note here: you seem to know quite a bit about good practices and the project is meant to disappear "soon" (though not right after you leave).

As Telastyn mentions, make the most out of this experience to learn what works and what doesn't and how to apply best practices in a real-world environment. Think about yourself first.

That said, best practices include keeping the code easy to understand for your colleagues, so as part of the learning experience, you should still strive to write good readable code. Using OOP to structure things properly is also a part of this and should naturally help make things easier to understand and maintain in the long run.

In my opinion, OO code should be easier to read because it's well structured, so I'm not sure why you need to make a choice between good code and intern-readable code. If interns do not know OOP well enough, this is an occasion to learn. I'd rather give good OOP code to new programmers so they immediately learn with good bases.

If you really feel the need to make things even more understandable, I'd consider adding comments to any part that, to you, is already looking complicated, such as when you struggle to get code you wrote days or a few weeks ago. If you struggle, imagine the effect on someone who never even wrote the code.

You may also go through your "old" code and suddenly realize a better structure based on later insights and you might spot duplicate code that can be turned into a function with parameters. That's when you may want to refactor what you have, if you feel confident the time spent doing it will truly help in the long run (still struggling with such estimates myself).

Adding unit tests or other form of test suites could also help you and anyone next as it can be run to ensure you haven't broken features of the existing code. I think it can be a great tool for newcomers as it's often hard to grasp the impact of modifying bits of code you don't know (even code you do know, really).

You might write some documentation on what your application should accomplish and giving insight into its most complicated aspects. Knowing what is expected behavior helps clarify whether you found a bug or a lack of feature (often a mixed up notion to final users).

Why not ask your colleagues? If they show knowledge of OOP and good practices and yet do not easily "get" your code, you could ask what they're struggling with and what's missing to help them understand.

Answer 2

The point of an internship is to learn. I would refactor the code to be better and ignore the assumed limitations of people you don't know. For all you know, the company will move that project to an internal team rather than interns soon.

Answer 3

Your question has two major concerns: should I write good code, even if the next person may not understand it? and, how to I make sure that my efforts are not wasted if a less experienced person takes over after me?

As to the first, you should always write the best code you can. We know that code written with design patterns and principles is flexible, maintainable, and extensible. Even new programmers can generally see this, even if they don't understand how to do it themselves. Tests also provide tremendous benefit, and can fill a documentation role as well. You cannot let expectations of who will come after you prevent you from writing good code; if anything, it should encourage you to write good code.

With regards to preserving all the work you've put in, most developers, even new ones, can generally understand what is going on in a piece of well-written code (at least on the surface), but some developers, especially new developers in school, have no idea why a piece of code is the way it is. This is what you have to communicate.

I would recommend writing a document to communicate how and why you got the code to where it is. I would briefly discuss how you use version control for the project, as some curricula do not involve any version control, and provide resources on where to learn about your VCS (for example, hginit.com and "Mercurial: The Definitive Guide for Mercurial, similar resources exists for other VCSes). You should talk about design patterns, especially which are the ones they'll see often. Once again, some curricula don't talk about design patterns. Once again, provide resources to learn more.

Also talk about the code, and your experience with it. Talk about conquering the 700 line method, how you did it, why you did it, and how it made everyone's life easier. I would write this less formally, and in a narrative tone to keep it interesting and personable. This will help the next person to see what progress you've made, see how you work, and build a personal bond. All developers can commiserate over experiences working with bad code.

I would leave out any specific details, like how to access your repositories or log into your servers, or confidential business information. The reason I would do this is so that they could send this out to an intern before they start, and they could keep it after they leave, as an informative resource. You should supply the other information in a separate document that they get once they actually start the internship. I would aim for a length between 5 and 10 pages, enough room for you to tell your stories while short enough to be read casually.

Programmers who come after will likely do the same thing you did (as you saw before where the list lived forever), if they can understand how and why to do it. If you build a good base, and clearly show the way, the next person is pretty likely to go with the flow.