How can I write good "research code"?

Question

"Research code" is often held up as a paragon of what not to do when writing software. Certainly, the kind of code that often results from trying to solve a research problem can end up being poorly-designed, difficult to debug, etc.

But my question is this: does research code have to be this way? Is it possible to write good research code? Is the only approach to consider the first version a poorly-written prototype to be discarded in favour of the better-designed second version?

Software engineering has all sorts of best practices about how to design and write good code, but I don't usually find this relevant when you don't have a good idea ahead of time what the final system will look like. The final system is likely to be a result of what did or didn't work along the way, and the only way to determine what does or doesn't work is to write the code first. As you find things that don't work, you change what the final system looks like, moving further away from your original design (assuming you had one).

I'd be interested in any personal experience with these issues, as well as any books or other resources anyone can point me to.

Answer 1

Is the only approach to consider the first version a poorly-written prototype to be discarded in favour of the better-designed second version?

No, but that approach is not a bad one.

Programmers should not be afraid to refactor code. It is not in the programmers job description that they must write programs that always work perfectly the first time; in fact, refining program code is what iterative development is all about.

Writing prototypes is a very pragmatic way to write software; the computer provides the ultimate reality-check of what does and does not work. With experience, good programmers follow best practices when writing their prototypes. If the result of a prototype concludes that a different approach is warranted, then a different approach is taken.

Good practices are not meant to be rigid unbending rules; they are meant to be guidelines. The same is true of software patterns. Software patterns provide models against which software that follows good practices can be written. They also provide a common vocabulary for programmers to converse in. But if all software problems could be solved with patterns, we wouldn't need programmers; we could just provide a computer with a set of specifications, and tell it to stitch together patterns for us to achieve our objective.

That is absurd, of course, and the reason it is absurd is because, like every good theory, best practices are good until they fail to address a specific problem, at which time you must find a better solution.

So the short answer to your question is, gain experience in best practices so that, while you are writing your prototypes, you can incorporate those best practices in sensible ways, and thereby reduce the amount of rework that will be needed during the subsequent rewrite.

Answer 2

I'd say that if you wish to do "research", by definition, you don't quite know what the answer is. And if you don't know the answer then you can't design the solution up front. That means you are likely to need to change the design as you go along and discover things about the problem you are trying to solve.

In this sense, writing the code well will make it cleaner, more flexible, and easier to refactor or redesign as your design changes. Badly written code will simply accumulate bodges and hacks and workarounds and add-ons until it becomes mangled to the point where you can't make much progress and are forced to rewrite it from scratch.

I've never found a valid reason not to write "good code" (except for the necessities: quick fixes are sometimes needed for immovable deadlines, and should be replaced as soon as possible afterwards. But even quick fixes should be well written shortcuts/compromises rather than poorly written bodges)

For me, rule number one for research code would be: Throw it away when you finish, and write any production code from scratch to the final design. This is perhaps the all-time most-broken rule of Software Engineering.

(Indeed, as a general rule of thumb, any code you write usually reaches its "peak" the third time you write it. An experienced programmer is simply someone who has written an example of everything at least 3 times)

Answer 3

Good software isn't written, it's re-written.

In my experience, exploratory coding works best when there's a flexible version control system (git, mercurial or other DVCS) available. Branching to try an idea and then selectively merging pieces between the branches works well.

Using a file common to all branches aids in tracking which branch has explored what area.

Answer 4

If you think that after you finish the research prototype, you'll code something of "production quality", then... just don't fool yourself. You will not. If you're in doubt about this--ask your senior researchers if they rewrote their ;-).

My suggestion would be to develop "research code" with just minimal best coding practices. Here's a question about this: Good strategies for developing throwaway code (and my answer). While it's seemingly about how to write throwaway code, it essentially contains practices on how to write your "throwaway" code in such a way that it won't be thrown away.

Answer 5

My personal experience after 20+ years of professional life hopping between academia and industry is that code is way better on average in academia than in industry.

By "better" I mean that people writing code in academia (again, in my experience) often have a better understanding of design and engineering principles. I have often found a slight disregard for the theory behind the code in industry, and that damages the quality of the code. Academics don't disregard the theory, and usually write better code as a result.

Also, systems are usually simpler in academia, which certainly helps write better code.