August 24, 2020, by uczenu
Programming – it’s all a question of style!
Today we look at the creation and potential reuse of programming code. An inordinate amount of code is created by researchers and academics at the University, but how much of it is ever reused? Is it possible to reuse it, potentially by someone from another faculty, school or department? Can it be easily understood by someone who did not create it?
There is a need to understand and reuse programming where possible in research, to avoid recreating the wheel, as it were. With this in mind, the following questions arise: (1) can programming code be reused in the future? (2) can this code be repurposed to tackle other research problems?
A key aspect of answering these questions is comprehension. Can someone else (be they an expert coder or not) understand what has been created within a programming script? With a few simple steps, it is possible to increase the ease of comprehension, structure code properly and — as a bonus — reduce the possibility of errors.
Code Style Guides
Style guides are a key aspect to the comprehension, maintenance, and potential reuse of computer code. There generally is a style guide for each respective programming language. For example, PEP8 is the style guide for the python programming language. It recommends that the maximum line length of code within a script be no more than 79 characters. This allows people to easily view the code on a screen without having to scroll to the right to see lines that go beyond a visual page limit. Fig.1 illustrates the application of PEP8 to a python code script, adhering to the guideline.
Figure 1: Python code with PEP8 style applied
Fig. 2 shows the option in RStudio that enables the column width of 80 characters to limit length of lines of R code. Additionally, there are a number of parameters that can help automatically format code in RStudio as code is generated, such as indentation and alignment (see fig. 3).
Figure 2: RStudio code display options (source: https://www.r-bloggers.com/)
Figure 3: RStudio editing options (source: https://www.r-bloggers.com/)
The following style guides are particularly useful:
– Python PEP8 style guide for python can be found here.
– R style guide can be found here and here.
– Matlab style guide can be found here.
– HTML and CSS style guide can be found here and here.
A nice overview of a range of style guides for differing number of programming languages is provided by ‘Kristories Awesome Guidelines’ on GitHub.
Code Ordering
An excellent way to structure code for ease of comprehension is to apply a code order template. Fig.4 shows such a template for python (used by Dr Urwin for teaching python programming), which has five distinct sections. The first is the program details, including aspects such the author, a description of the program, its version number, date created and last modified. The second is placing the imported modules at the top of the program script. The third is a section for global variables before the fourth, that of the functions. The final section is for the main program code where the program is executed. Formal layout of all code is an important aspect regardless of the language used. Using such an approach makes code much easier to read, troubleshoot, test, and maintain. Moreover, it can reduce the number of errors throughout a program’s lifetime.
Figure 4: Python code template
For R program code a good general code order to apply is thus in fig.5:
Figure 5: R code order
Code order templates can drastically improve the readability and maintenance of code by making it easier to find where certain aspects of code are.
Variables
The naming of variables within a program is important. All variable names should be (1) unique and (2) meaningful. Properly naming variables dramatically reduces confusion and aids comprehension. Fig.6 shows an example of good and bad variable names using python.
Figure 6: Variable naming in python
Comments are Key
One of the key aspects to understanding program code is comments. Programmers need to explain each section of a piece of code they have created if other users are to fully understand ‘why’ the code is doing what it is doing. The process of adding comments should always be done when a piece of code has been finalised and no further changes to the structure of the code will take place. Two excellent examples of commented code are displayed in fig. 7 and fig. 8.
Figure 7: R code comments (source: http://web.stanford.edu/class/cs109l/unrestricted/resources/google-style.html)
Figure 8: Python code comments (source: https://realpython.com/python-comments-guide/)
Research Community Hub
Producing easily readable code fulfils part of the reuse approach being developed by the ‘Research Community Hub’. This is a digital research project at the University of Nottingham that aims to provide solutions to such issues. It will be developed over the next two to three years with the aim of providing a ‘user developed’ service that fulfils the needs of researchers and academics alike. The Research Community Hub must be easy to use, intuitive and fulfil the needs of the research community.
The Digital Research Methods team are currently developing the Research Community Hub, a tool to help improve your life as a researcher, accelerate your research, and improve the chances of funding.
Over the coming months we invite you to take part in:
1. Researcher workshops – These run twice weekly, plus when you want them to. Learn about the project, tell us your current problems and future needs. To book a workshop place click here.
2. One-to-one meetings – we want to find out ‘your’ research needs, you can find out how to share your research to help reuse and promotion – please email esmond.urwin@nottingham.ac.uk.
3. Surveys – tell us ‘your’ research problems creating, using and finding data, research information and peoples’ expertise. Take a quick survey click here.
If you are interested being involved, or just want to learn more, please contact us:
https://www.nottingham.ac.uk/it-services/digital/team.aspx
Sorry, comments are closed!