22

I am doing my master thesis on wireless networking. I am working on the source code, which the writer of one of the articles provided to me. Initially, I sent him an email and I asked him to send me his C++ source code . So he did. But the problem is, there was no documentation for his code and he is the only one that knows anything about this codebase. As a result, I totally depend on him. Last night I sent him an email and I asked him a question about his code and he replied to me very quickly, only three hours later. Probably, I will need his help again.

Before my last night's email and after spending one month working on his code, I saw minor progress to my work. But after yesterday's mail and his guidance, my work was significantly accelerated. I will probably need his help again maybe another two or three emails in a week. But I am afraid he will become angry with me for sending him a lot of emails.

So what should I do? Assume you are the source code programmer. Do you think he will become angry about my emails? Or he will be willing to help (since I will cite his article)?

  • 19
    If you are writing a paper you could offer him coauthorship, which might serve to i) compensate his time spending and ii) motivate him to write back to you. – Miguel Aug 25 '14 at 13:51
  • 5
    @Miguel You should check carefully the conventions for authorship in your field before offering anyone co-authorship. Contributing background understanding is not normally considered enough for co-authorship. E.g., suppose that you write paper Y that extends my paper X. In my area, if all I did was explain X to you and answer your questions about it, I would not expect to be a co-author of Y because I didn't do any of the work in that paper (an acknowledgment would be reasonable). The extreme version is that you don't give co-authorship to your primary school teacher who taught you arithmetic. – David Richerby Aug 25 '14 at 14:19
  • 4
    @DavidRicherby I don't mean "offer authorship" as simply putting his name on the paper, but as getting him involved with it, preparing the manuscript, etc. – Miguel Aug 25 '14 at 14:43
  • 11
    Putting myself in the shoe of the programmer: On a bad day (daughter wet the bed, dog bit his leg, wife accidentally dropped coffee in his lap, just to start) even the second e-mail will be two too-many. On a good day (just finished a project and got a raise, daughter graduated from kindergarten with top marks) perhaps even 10 is ok. My point being: there is absolutely no way what any of us say about your second or third question can be of any use to you. As to your first: the most profitable (though not necessarily the nicest) would be to send e-mails until he gets tired of answering... – Willie Wong Aug 25 '14 at 15:23
  • 4
    @Miguel I have never heard the phrase "authorship" used in the context of academic papers to mean anything other than "having one's name in the list of authors." – David Richerby Aug 25 '14 at 16:33
37

Although your intentions are probably good, you seem to take advantage of the creator of the source code. He is not your personal debugger nor he must be the one writing the code for your thesis (especially for free). He has written a paper and he has given you his source code. That is all the information you need to know. Read his paper (or his paper slides if they are publicly available) a hundred times, till you know every little detail of it and then look at his code (another hundred times) until you correlate everything between the paper and the code. Of course this will be slower than sending him a couple of emails but it is YOUR thesis not his. Only when you do all this and still there are unanswered questions, then collect all the possible questions you might have (including queries about his code and his paper) and then send it him ONE email, with all your questions. Anything more than that is exploiting his kindness. This kind of back and forth emails with questions is one of the many reasons why many people are unwilling to share their codebase.

Since he is probably a nice guy, you should consider that in the future you might collaborate with him or need his help. Being pushy or lazy (and delegating your work to him because you do not want spend 1-3 weeks refactoring or studying his code more carefully) is a sure way to burn bridges with him. And you really do not want to do that.

On the other hand, if after giving you access to his source code he understands (by your email) that you did everything humanly possible to understand his code and paper and just want some extra help, he will be willing to assist because: a) you seem to appreciate his work b) you seem to understand his time constraints c) you are also a smart, hard working guy worth collaborating with. And this is the message you need to convey.

  • 9
    I'm not sure you can conclude at this early stage that the asker is taking advantage of the code's author. A few emails a week forever would certainly be too many but a few emails a week for a short time might not be excessive. Also, you say that delegating work to the code author would be unacceptable but the asker never proposed doing that. I do agree with your last paragraph but I'd replace "that you [already] did everything humanly possible to understand" with "that you made a serious and sincere attempt to understand." "Everything humanly possible" is an impossibly high bar. – David Richerby Aug 25 '14 at 15:27
  • 1
    1st email: Give code. 2nd Email: Explain code. Why do you need a third mail, when you could gather all your questions on one email? – Alexandros Aug 25 '14 at 15:32
  • 4
    First, I don't see why you think that one email containing ten questions is better than ten emails containing one question each. I'd much rather have somebody request several small blocks of my time than one big block, since the small blocks are easier to fit into my schedule. Second, if part B of the code depends on part A, you probably can't even formulate sensible questions about B until you understand A. And if you can't understand A without asking questions, then you need two emails of questions. – David Richerby Aug 25 '14 at 15:44
  • 2
    @alex. I know what you mean. But 16 files and 10,000 lines is not that big if it is organized per functions. You just use an IDE and check which function calls what. You do not need the details of each function you just need to understand the variables and what each function does at a high level – Alexandros Aug 25 '14 at 17:48
  • 5
    @Alexandros Any statement about software that includes the phrase "you just" is patently false. (The previous sentence, of course, is not about software, but about statements about software.) – JeffE Oct 5 '14 at 23:14
31

Why not just ask him? He knows how busy he is, how interesting your project is for him, and how dumb (if any) your questions are. You can also offer to pay him back by writing a (partial) manual on his code, as you go on understanding it.

If I was to receive this kind of email I would see that you are acknowledging my effort and trying to be respectful with my time. And maybe this will be good for me, forcing me to rethink aspects of the code, and make a mental note of doing better documentation in the future.

Also, in that situation, I would greatly appreciate to be kept in the loop about your project. Even if I can't or won't help, I would like to see the the progress.

A quick answer is usually a good sign, it means that he finds your questions interesting and not something you should have been able to figure out by yourself. In any case, if you want to make sure, you can ask someone that is roughly familiar with that code (probably your advisor), and see if the questions are indeed something you should have been able to figure out by yourself; and if you are not, they should teach you the techniques you are missing to do it.

All this said, I have been given messy code to work with three times, and the three of them I ended up grabbing the paper and reimplementing it myself in a couple of days (and in two of them, the result was way better). Maybe your case is too big, but you should consider it.

  • 2
    "forcing me to rethink aspects of the code" or, as the case may be, responding that I no longer care about this code, never intended it for publication, provided it only because to do so cost me nothing, and do not wish to have to revisit it to answer difficult questions about it. The point is, by asking you find out one way or the other and don't occupy any time the author doesn't want occupied :-) – Steve Jessop Aug 26 '14 at 16:33
9

As someone who is often on the receiving end of such questions, my advice is:

  1. First and foremost, understand the theory behind the code before you go ask questions. Many of the questions that I get about my code reveal that the person with the question simply doesn't have basic background knowledge in optimization (e.g. "what's a Cholesky factorization") without which they couldn't possibly understand the code.

  2. Make sure that you have the latest version of the author's code. Don't use an earlier version.

  3. Understand how the software is licensed (if at all.) You will have to work within the terms of that license (e.g. the author might have put the code under the GPL, and your derivative work will also have to be GPL.)

  4. Don't complain about the quality of the code or features that it lacks. If it doesn't do what you need, ask ask the author whether this is possible within the current code, or by a simple extension or whether the algorithm fundamentally doesn't handle that case or whatever. Do not assume that what you want will be easy or even possible at all. Depending on the author's response, you might get a ready made solution, or you might get some information on how to modify the code, or you might get told that it isn't practical.

  5. If you're getting errors, then please provide the input data and output so that I can recreate the problem. Make an example that reproduces the problem as simply as possible rather than giving me all of your code. I will attempt to recreate the problem on my machine.

  • thank you very very much. In case four, If I send you an email and then tell you, I want to expand your code in order to make your code to support "X" feature --how I should tell you this ? to make you more willing to help me, by the way I read your paper more than five times and I understand all part of theory. and also my thesis is about the effect of "X" feature. – M R R Oct 6 '14 at 3:26
  • 3
    Well, for open source software, there's no way that the author can stop you from modifying their code and redistributing it with the modifications. However, it's probably better for everyone involved if you and the author of the code can work together to incorporate your modifications to the code. I'd start by explaining to the original author of the code what you're planning to work on, and then listen to what the author says, which might be "This has already been tried and failed" or "Hmmm. That's an interesting idea, let me know how it works" or you might get an offer to collaborate. – Brian Borchers Oct 6 '14 at 3:49
2

To some extent I'm probably repeating what others have said here already. But in any case, here I go with my 2 cents.

First, the situation you describe is actually quite unusual. In most cases where code is used in a publication, the code is not published, and if it is not published, it is often unobtainable from the authors. If they do provide it, they are not very likely to answer questions about it. For example, often the code is written by some junior person like a grad student, and once that person has departed, the senior authors, who are also the corresponding author, don't know anything specific about the code, because they have not actually written any of it. They may also no longer have a copy of it, if they ever did.

So, you are already in a good situation, that someone is responding to you.

Another thing to bear in mind is that academics like people to be interested in your work. Since your correspondent wrote the code, he is probably the main author of the work; people who write the code generally are. So, he may not mind answering questions about his work as long as they are not stupid. Avoid basic/general language-related questions which are not specific to the code, for example.

As someone else said, if you want to know how he feels, why not ask him? So, I'd suggest three concrete things.

  1. Express your appreciation for the time he is spending replying to you. Don't go overboard; a sentence or two is enough. But it is important to do so.
  2. If you interested/willing to have him as a co-author, ask him if he is interested in being a co-author. If he is not interested, or you don't want him as a co-author, ask him permission to add him to the acknowedgements. You should certainly add him, if he agrees.
  3. Ask him if it is Ok to keep asking him occasional questions. Perhaps outline what and how much you expect to be asking him, if you have an idea, so he knows what to expect.
  4. This is going above and beyond, in some sense, but since you say his code is not documented, document it, perhaps checking with him first about how to do so, in case he has preferences. Then, send the documentation to him. That's a nice concrete way to show appreciation.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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