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

  • The amount of time you spent understanding the code can be spent by the next intern to understand basic OOP concepts. – metacircle Jul 17 '14 at 8:53
  • 1
    @BaronSchnitz A bit on the humor side. Time travel LOL? How can you possibly teach previous interns? Haven't they already left? – InformedA Jul 17 '14 at 9:08
  • @metacircle I am indeed implementing OOP design, I am just trying to write code that is well organized and extendable but also quickly understandable. The idea is to teach the future intern a better alternative than what they are likely to use (statistically not good practices). (edit: missing time machine) – BaronSchnitz Jul 17 '14 at 9:10
  • @BaronSchnitz So don't bother. Refactor the code, make yourself happy, make the company happy. If the next intern does not grasp OOP concepts he must learn them to understand the code you left. Just as you had spent hours in the debugger to understand the code. – metacircle Jul 17 '14 at 9:11
  • 3
    What an interesting problem. Glad to see this isn't a "shall I throw out the code base" question. It's perfectly possible to have good code control access to a pile of spaghetti with some intention to refactor down gradually. Anyway, limit your expectations to some extent because in the end this sounds like a sort of an intern sandbox. – Nathan Cooper Jul 17 '14 at 10:11

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.

| improve this answer | |
  • Thanks for the input! I am not choosing between OO code and some alternative "better readable" code. I am trying to implement OO code in a form that is especially easier for a newcomer to understand and start working with. – BaronSchnitz Jul 17 '14 at 13:04
  • To clarify, imagine the case where good OOP code does not imply readable code (although it certainly does). What property of my code could be emphasized or changed in order to make the code readable and appealing to someone coming from a background where OOP principles have not been stressed as good structure. – BaronSchnitz Jul 17 '14 at 13:12
  • 1
    You should focus on writing good code first. While it might be true that the previous intern's code is very bad (I don't know I haven't seen). Just focusing on the bad code of other sometimes might make you feel over-confident in your own ability. I personally don't think you should worry for the next intern to this point. Who knows, he might turn out to be a guy much smarter than all of us here and in turn going here to talk about your noodle code this time next year. – InformedA Jul 17 '14 at 13:26
  • @randomA Good point. The previous interns' code is bad enough to make most regular code look very good. I don't think it I am stuck in an overconfident, superior mentality. I am just focusing on creating something that is "good enough" to be much easier to understand than what I was given and promotes better organization and programming practices. I'll scour all the noodle code questions dilligently in hopes that a super smart intern asks about my code. I'm sure it would be a great learning (and humbling) experience – BaronSchnitz Jul 17 '14 at 13:33

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.

| improve this answer | |
  • Thanks for the tip! I am, however, very aware of what will be done with the tool after I leave. It will continue being extended by interns for two more years until this branch of the company switches to a newer standard, at which point it will be made obsolete. I do view this as a great learning experience as to what makes code optimized in terms of readability, not just in general but to the extent that it is especially friendly for beginners. – BaronSchnitz Jul 17 '14 at 11:57
  • @BaronSchnitz - catering to the least skilled seems like a poor approach to making quality software. – Telastyn Jul 17 '14 at 13:54
  • This is why I asked this question. How do I balance writing good code with writing it so that it is conducive for the next intern to write good code (or wish to learn to do so). I asked because I do not have the outlook or experience to make this judgement effectively on my own. (Note: When I say balance I do not mean to imply that these two things have the same weight/importance, better code is much more important to me) – BaronSchnitz Jul 17 '14 at 14:04

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.

| improve this answer | |

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