Academia Stack Exchange is a question and answer site for academics and those enrolled in higher education. It only takes a minute to sign up.
Sign up to join this community
This question is related to Physics research papers, particularly one that will be coming up for my ongoing PhD research (4th paper in all).
A core part of the research is developing, testing and validating relevant self-written code. So, my question is how much of the code should be included in the upcoming paper? Should it be the whole thing, or a written summary of the main components/subroutines used?
If the goal of your paper is to show that your code solves a particular problem or performs a specific task, then it is your responsibility to prove to the reviewers that your code does what it claims to do. The easiest way to do this is to include the code as part of the supporting information for your paper.
However, reproducibility—which is what you're asking about, to a certain extent—is a not-so-simple question when it comes to showing codes do what they're supposed to. For instance, a code that runs one way under one configuration may return a slightly (or perhaps _very) different result when run under another configuration. This doesn't mean that one result or the other is wrong—it just means that this behavior needs to be taken into account when evaluating the correctness of software.
One way to help this is to provide as much information as possible on your testing environment, so that any differences between the system on wich you were working and the conditions the reviewers and future potential users of your code will have can quickly be identified. This would be included, perhaps, as a text file that accompanies the code in the supporting information.
I would second @NPcompleteUser's answer about having the code and some sort of walkthrough for reproducing your results online. However your question about how much to include in the paper is very journal specific. There are a number of publications specifically for computational science with formats where large chunks of code are expected, but if it's a journal whose focus is more on the science than the techniques, I would just describe in words the tricky parts of your algorithm and give a footnote reference to the website where the code lives.
I would put the current version [of the code] on gist. Providing inputs and gnuplot (matplotlib/whatever) scripts for graph reproduction.
Papers on physics which utilise code should primarily describe the algorithms and their relevance to the physical problem at hand, and not focus on nuts and bolts of the code. There are several reasons for this: the printed article is the wrong place to include code, as page space is generally limited and not suited to formatting of code; there are issues with copyright as in most cases the ownership of the code is transferred to the journal, or if open access then put in the public domain; generally the audience of a paper should be broad enough to be useful to a wider range of researchers than your specialist area.
As others have suggested, you should release your code on GitHub or similar and apply a suitable licence, and simply refer to it in the paper. There are some exceptions to including code in a paper, generally when understanding the algorithm is essential for the reader or complicated, in which case pseudo code is acceptable since the essential information is included without any language specific distractions.
Another option, in the field of astrophysics, is to submit your code to a repository, and register it in the Astrophysics Source Code Library (ASCL) at https://ascl.net, which is indexed by the SAO/NASA's Astrophysics Database System (ADS), the official compilation of literature (and now source code and datasets) in astrophysics.
If that's your case, you look at this link to find out how to submit your code to it: https://ascl.net/submissions
The page has additional resources telling you how to cite said codes, and this is what a citation might look like:
Garrido, J. et al., 2013, AstroTaverna, Astrophysics Source Code Library, record ascl:1307.007
With the record being held at https://ascl.net/1307.007, and the ADS entry at http://adsabs.harvard.edu/abs/2013ascl.soft07007G
