16

My paper is about a specific application of blockchain. I've developed a basic prototype for it and so far, I've described it in detail, and put screencaps of the interface for it. Should I also include actual code of relating to different parts of the application?

  • 3
    Practical matter: you'll probably find silly bugs in your code later, and it'd be nice to be able to fix them without having to issue a revision to the paper. – Mehrdad Jul 8 at 19:01
  • 9
    Upload your code to GitHub and include a link in the appendix. Including your code will make your research more reproducible and help reviewers spot issues, and GitHub (or GitLab, etc.) is a better place to share code because it supports version history and collaboration. – Qaz Jul 9 at 2:28
  • 2
    I uploaded the code for my Master's thesis to github and just included the URL in the paper. The down side is now I'm committed to keeping that repo up there, but it definitely makes it far easier for others to use or check the code. My advisor was delighted with the solution. – Kathy Jul 9 at 13:48
8

As mentioned in the answer by lordy, it is going to depend heavily on your field and journal. But to expand on things, here are a couple thoughts about including code directly in the content of the paper:

  • Programming language: You're code is going to be in just one of the many available programming languages out there. That might limit its usefulness or make it more difficult for people that are not familiar with that language.
  • Line lengths: Often it is hard to write readable code that fits into the line length of a single printed page. You have to resort to things like shorter, potentially less useful variable names, splitting lines, etc. Also, different journals might use different fonts that change how many characters fit on a line, so you might have to spend a lot of time just reformatting the code for different submissions. It's worse if it has to be in a single column of a two-column layout.
  • Conciseness: there might be a lot of things that people don't need to see to understand the actual application of your paper, like initializing variables, unrolling loops, etc. This is just wasted space that may count toward word limits.
  • Future-proofness: Ideally, you don't want any part of the main content of your paper to become obsolete in the future. Technology changes, standards change, etc. Eventually your code could become unrunnable. It's probably impossible to avoid altogether, but including it in the main body of the paper just makes it more prominent if it does happen.

With that, here are some alternatives, some of which have already been mentioned in other answers/comments:

  • Pseudocode: basically the same as including code, but negates/offsets most or all of the negatives outlined above.
  • Supplementary info (SI): Many journals allow the inclusion of supplementary material. You could potentially include your code here. This has the advantage that no matter what, there will always be an archival record of your code associated with your paper that you don't have to spend time managing.
  • External repositories (e.g., Github): This makes you responsible for ensuring the code continues to be available for readers, and also depends on the service's continued existence, but has the upside that you can fix mistakes, add features, etc.

There's nothing stopping you from including all three options. Pseudocode provides permanency for describing an algorithm, supplementary info provides a combination of permanency and utility for an example implementation, and an external repository provides utility and future-proofness for actual mainstream use.

24

Depends on the field and journal - check other papers in the same journal on how they do it. In my field (Bioinformatics) we usually do not put code into the paper but provide the full source code via the department web-page and/or git.

  • 19
    I would even go as far as: never put code in a paper, this is what we did some decades ago. repositories as github are for this purpose. And I concur: yes, please put code and data somewhere public so that others can use and reproduce your results. – Marco Lübbecke Jul 8 at 9:49
  • 5
    I would only include code snippets or pseudo-code snippets if it helps your readers understand a particularly tricky part. If it takes up more space than a table or figure, it's too much. But, as lordy says, use the norms of the journal. – Van Jul 8 at 11:59
  • Even then I would argue that if you only use widely known algorithms it should be sufficient to simply name them. (Although I don't know if this is the case here.) – HerpDerpington Jul 8 at 18:22
  • 2
    @MarcoLübbecke Combination of GitHub link and code in appendix seems the best to me; just think of all the code from papers that would have been lost in the past if it was exclusively hosted on one of the now defunct servers. – Luaan Jul 9 at 10:45
  • I would recommend not to use only departmental websites as they might change in future due to any rearrangement or university policies. Best case is to upload on multiple public sources so even if one changes/expires, others will be accessible. I have specifically observed this in Bioinformatics area. Lot of tools have generated and lost their URL from the paper some 10 years later. – Dexter Jul 9 at 13:32
4

Your topic sounds like the paper would benefit from having the core algorithms as code in the paper, but you should probably use pseudo code with explicit declarations and everything.
Read a few other papers and look at the corresponding LaTeX packages, to get a rough impression how a good pseudo code listing should look like.

Do NOT:

int random_element(std::vector<int> mylist) {
  std::random_shuffle(mylist.begin(), mylist.end());
  return mylist.at(0);
}

Do:

Input:  A non-empty list of integers "mylist", a "shuffle" function that
        creates a random permutation of a list
Output: A random element of the list
-------------------------------------------------------------------------
shuffled_list ← shuffle(mylist)
result ← shuffled_list[0]
return result

Your reader should not need to understand the details of your programming language and many of them are implementation specific and have nothing to do with the algorithm itself. Your reader needs to understand the abstract method and is in general not interested in if you use smart pointers and other technical details.

The same applies for your screencaps. Are you sure, they are needed for the paper? Keep it at a minimum, if you're not explicitely writing about user interface guidelines. There are many ways to implement an UI for a specific application and when describing the method, it does not matter how you arranged the buttons.

Such things may be put into supplementary material, for example by putting your code online for others to read and try (possibly with a documentation including the screencaps and compiled binaries with the UI for easy testing).

3

I agree with @anjama.

The idea of an article is to communicate ideas, and listing code in an article is fine as far as it makes the article more readable and the code itself presents necessary clarification. To do so, the code should be clear and self-contained. That is all function names or variables do not need references to other code files that are not presented in the article.

This practice can be easily replaced by pseudo code instead or diagrams, and I would only put code in a paper if the paper describes how to use the code itself. For instance presenting how to use/call classes of a package I have developed. The reason is for avoiding putting code is that, which programming language I am going to use, the reader might not be familiar with it, and if things can not be communicated with pseudo-code or diagrams, then the code itself might not be clearer, since pseudo-code is developed in the first place to abstract the idea of code listing.

To summarize, use instead pesudo-code or diagram, and only list code to explain how to use a software package that the paper describes.

2

As others have written, code belongs in a public repo. I have one addition to make:

The only time I have ever seen code in a paper was in a paper presenting a new simulation tool. To demonstrate the ease of use and flexibility the short code snippets producing the plots were part of the figures (see here).

In a similar way, if you e.g. want to showcase a particularly nice or convenient API, it might be appropriate to have (minimal!) code snippet in the paper.

0

There are some papers in the machine learning field where an algorithm is complex, and a certain language (i.e. Python) is ubiquitous. For these papers, they usually first include a pseudocode description of the algorithm in the main paper, and add a minimal implementation in an appendix. You will have to decide if you believe that your idea is truly clearer to a majority of your readers if written as a code snippet.

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.