Knowing when the code is good enough, for research

Question

My question is in a similar vein to this one.

My research requires code. I can write code and I know some things about writing good code. Both for readability, (e.g. standardised doc string, descriptive variable names, comments that describe the intention) and safety (assertions in the code, unit tests, sensible error messages). Adding these things takes me more time than omitting them.

At present I will typically do a bare minimum on my first attempt. So I will put a one line doc string in; use descriptive, but occasionally inconstant, variable names; and few comments. If the code doesn’t work first time I will go back and add unit tests and generally improve it's quality until it is functional.

If at a later stage part of the code needs altering significantly, (perhaps I realise I need it in parallel), then lots of the "polish" will need redoing. This does not make it enticing to polish more earlier on. Occasionally I will chase my tail over a fault that turns out to be originating in an older section of code, that I might have caught if I have been more thorough first time.

The code I write is almost always only used by myself.

Clearly there is a trade-off between doing things by the book and producing results fast. What would you look at to decide if you had found a good balance between these things?

Answer 1

As the

code I write is almost always only used by myself

you only have yourself to please. So the only sensible answer is to balance things to minimize the frustration to yourself. Don't do things you see as frustratingly slowing you down until you are more frustrated by the problems caused by not doing them.

However, the more strategic question is whether you want to continue writing code that will only be used and seen by yourself. If you want to advance your career through collaboration with peers, or by building a group of researchers to work on and with your codes, then it will be better to do more earlier.

You then know you've found a good balance when the collaborators you want to work with still want to work with you after they've spent some time with your code.

Answer 2

You said:

The code I write is almost always only used by myself

but I find this remark a little short-sighted.

In the moment, code may be used almost exclusively by the author/student-researcher, but eventually that student will graduate, and there may be some follow-on research to do. Woe to the next graduate student who inherits that mess, or the summer intern who gets hired to clean it up!

There are plenty of good reasons to invest a little time in writing better-engineered code:

• You (and others who may join the research team) will be able to further build upon a well-designed architecture
• What seems “self-documenting” now may be harder-to-follow than you think six months from now
• A lot of code gets ultimately gets used for longer than the original author speculated
• The more complex your code becomes, the harder it will be to debug later

Sure, there’s a tradeoff between immediacy of results and building for the future. But I’d cautioned against getting lulled into a false sense of security and churning out code as fast as you can with little regard to future maintainability and extensibility.

Answer 3

As you would with any other document, write for your audience. That is, write your code to make it help, as best as possible (yet still at reasonable cost), those who are reading it. Consider:

1. Will anybody other than you be reading the code, now or in the future? If it's a one-off script that you will quickly discard you need not worry much about readability. If nobody else is likely ever to look at it, you need to think about how likely your future self is to remember what was going on at the time and understand the conventions you used.

2. If others are likely to read your code, how technically adept with that particular language and libraries, and in general, are they likely to be? Can you use standard conventions used by programmers experienced in that language? Do you need write things in a way that experienced developers who don't know that particular language can quickly understand what you're doing? Do you need to avoid standard things (e.g., list comprehensions) that inexperienced developers might not understand well?

3. How well will the other developers understand the problem domain? Do you need to provide a detailed explanation of what you're doing and why you're doing it, or do you expect that when they look at a line they'll, e.g., immediately see that it's a form of Black Scholes equation and understand how and why it's being used there?

Keep in mind that making things more descriptive and adding more comments does not necessarily make your code more readable; for some audiences that may even make it less readable. Just as mathematicians can more quickly comprehend a dense equation than a long description of the equation written in "plain English," experienced developers familiar with a domain will take considerably longer to read verbose code written for a beginner than they will tight code written for an expert that communicates exactly what is needed and no more. As an extreme example, read this:

def double_a_number(number_to_be_doubled):
    ''' Given a number, this will return twice that number.
        Parameters:
            number_to_be_doubled: the number to be doubled
        Return Value:
            The doubled number.
    '''
    return number_to_be_doubled * 2

and then tell me if you think anybody would find it easier to understand than:

def double(x): return 2*x

Also be careful not to fall into the classic trap affecting inexperienced (and, sadly, even many experienced) developers of putting slavish devotion to rules ahead of the readability that those rules were supposed to promote. "Inconsistent" variable names and the like are not necessarily a problem (except for whomever is writing your lint configuration files) if your focus is on communicating with other developers rather than satisfying arbitrary rules.

And my last bit of personal advice, since you mention docstrings, always remember that a comment is only there because you couldn't write clear enough code. If you feel a function needs a docstring, look first to see if you can't improve the function name, change positional parameters to named parameters, or use any other techniques to make the code state more clearly what it's about. (And if someone's telling you to put in docstrings anyway, refer them to my example above.)

Answer 4

I think for the main question, "when is the code good enough?", the answer is simple: when it does what you want it to do, and you can be confident that the answer it gives you is correct.

There is definitely a trade-off for making your code nice, however. To me, that comes up in two places:

1. What if, six months later, you want to revisit your research results and see if you can come up with some improvements, or maybe you had hit a dead end so you are coming back to see if you can finish the work. Can you read your code from six months ago, and pick back up modifying it? Or is it too convoluted to follow and use? Ideally, you should be able to come back to your code in a year and easily understand what you were doing.
2. Your research does not exist in a bubble. Your next research project will probably be somewhat related to your previous one. Can your code be reused? Can parts of it be reused? Even if there are few benefits in your current project to making your code nice and modular, you may save yourself lots of time and effort down the line if you do this. Important functions and algorithms can then be moved over to your new setting with minimal adaptation. A side benefit is that you can replace certain pieces of your code with alternate implementations to see if you can get better results.

Answer 5

How careful you are should be a pragmatic choice.

The point of the disciplines is to help you write working code (which you can keep working and extending).

This is not an academic exercise (Perhaps this is the wrong forum in which to make this comment). There are "no points for box-ticking good practices" (perhaps there are in your environment).

The good practices are hard-won lessons from the commonality of programming practice. In an environment where many programmers collaborate on code, which will often be maintained over a longer time than ever anticipated, they help to limit the confusion and re-work needed.

You sound like you are well on the way.

If you are near the beginning of your programmer-journey, I would recommend you explore the meanings of "DRY", "YAGNI" and "SOLID". And I would put in a special mention for unit testing.

In my own experience, unit-testing:

• helps you document what you intended the code to do when you sat down to write it, and it will let you check that it is still doing it, even when you make some apparently completely unrelated change miles away in your code, months later. Including little details like nothing will be reported as null or nothing will be reported as empty-string.
• winkles out your misunderstandings of your primary language or the associated framework and libraries you merely glanced over the documentation for, before adopting. These misunderstandings make for time-consuming bug-fixing if you have to find them out by debugging the consumer of your mis-implemented code.
• will encourage you to write appropriately granular code: it is such a nuisance trying to write unit tests for code which tries to squeeze too much activity into each routine (method, subprogram, etc.).
• is best begun before you actually create the code which it will later test. This might help you to focus more clearly on what your code ought to deliver.
• will find out early for you, when your early code-design needs to be thrown away. This will discourage you from soldiering on with a wrong design which you've made too much investment in already to be willing to throw away. It's all about making working code, not about enshrining your first master-plan.

Answer 6

You say:

The code I write is almost always only used by myself

Like others, I don't share this opinion. The code is GUARANTEED to be used by at least two people:

1. You
2. You three months from now.

Good internal documentation doesn't take that long, and will in the long run save you time and effort.

Answer 7

The code I write is almost always only used by myself.

This comment seems somewhat misguided and I should predicate this by saying I write a lot of research code myself as well. The reason why I think this statement is misguided is because the code is being used for something (e.g., prepare data for analysis, analysis, modeling, etc.) and is ultimately going to impact any manuscripts you prepare. As such, ensuring that your code is readable by others is part of ensuring that your work is repeatable by others as well. Furthermore, if your code solves a problem that others have (quite common in research as well!) others may as for part of it to use in their own research.

That being said, with practice it is possible to write fairly readable code the first time around and just requires a bit of discipline. Some IDEs will force this upon you by checking variable names (e.g., do they conform to camelCase?), function names, function length, unit test coverage, and so forth. This tends to be a lot since it is unusual for people to go back and spend a lot of time improving code - once you have the results the bias tends to be to move on to the next project.

So the bottom line is that you should try to write code that is good enough to share with others the first time around. You never know when a reviewer may ask to see the relevant source code.