{"id":188,"date":"2025-12-10T12:39:54","date_gmt":"2025-12-10T17:39:54","guid":{"rendered":"https:\/\/pressbooks.bccampus.ca\/openscholarship\/chapter\/open-code\/"},"modified":"2026-02-12T15:10:39","modified_gmt":"2026-02-12T20:10:39","slug":"open-code","status":"publish","type":"chapter","link":"https:\/\/pressbooks.bccampus.ca\/openscholarship\/chapter\/open-code\/","title":{"raw":"Open Code","rendered":"Open Code"},"content":{"raw":"As we mentioned in the first section, a key element of open software includes using tools that enable human and machine interpretable content so that even if a particular piece of software is no longer available, a human should still be able to understand what the intent of the code was.\r\n\r\nWhen we talk about open in the context of creating human and machine interpretable code, we\u2019re talking about organized, documented code supported through scripting and literate programming.\r\n\r\nPrograms can be shared either as source code (as the programmer wrote it) or compiled (a format intended only for machine-reading, not to be read directly by people). Sharing a compiled program allows someone else to use it, but does not allow them to see the internals of how the program operates, or modify it to behave differently.\r\n

Readable Code<\/h2>\r\nIt\u2019s all well and good if we make our code available by the ethos of Free and Open Source Software (FOSS) and engage in literate programming when compiling our data and outputs. But if the syntax and structure of our code are not clear, we are no more transparent than the black box of 0s and 1s we are trying to overcome.\r\n\r\nWriting clear code that a human can make sense of is critical for both transparency and reproducibility in the research life cycle.\r\n\r\nSo, what does readable code look like? The following video Readable Code (3:59) from Khan Academy gives a pretty good overview of how code can be made more accessible to a human reader. Don\u2019t focus on the actual coding language but on the principles of making it readable.\r\n\r\nhttps:\/\/www.youtube.com\/watch?v=_u-fqfr86Ro\r\n

Readable Code | Computer Programming | Khan Academy(2014). By Khan Academy.<\/sup><\/a><\/p>\r\nThere are a lot of opinions out there on just what makes readable code readable code. After all, some of our most beloved authors break all the rules of good grammar. Some manage to explain the world in a single sentence, while others will fill pages with the briefest moment. In general, this concept is captured well in the WTF per Minute measurement:\r\n

\r\n
\u201cCars have MPH (Miles per Hour) that measures the speed that they travel. The better the car the faster the MPH or speed. Developers have WTFPM (WTF per Minute) that measures the number of \u2018Works That Frustrate\u2019 that the developer can read per minute, aka code quality\u2026With a car, the BETTER the road the more MPH it can attain. With a developer, the WORSE the code the more WTFPM can be obtained.\u201d\r\n

WTF Per Minute \u2013 An Actual Measurement for Code Quality <\/a><\/p>\r\n<\/blockquote>\r\nThe short of it though is that all rules will be contextual, depending on why you\u2019re writing what you\u2019re writing and who your audience is. As well as the reality that conventions exist in certain circles of programmers, researchers, and learners.\r\n\r\n<\/div>\r\n

\r\n\r\n\r\n\r\n
\r\n
Dig Deeper<\/h5>\r\nWritten for programmers, the introductory content in this book is widely applicable: The Art of Readable Code: Simple and Practical Techniques for Writing Better Code<\/a>, by Dustin Boswell and Trevor Foucher.\r\n\r\nNote<\/em> The above text is available only to UBC Library card holders. We\u2019re actively seeking an alternative that is open. In the mean time, you can check availability at your local library using WorldCat<\/a> and putting in your postal code.<\/td>\r\n
\"\"<\/td>\r\n<\/tr>\r\n<\/tbody>\r\n<\/table>\r\n<\/div>\r\n

Using GenAI Tools to Create Readable Code<\/h2>\r\n[pb_glossary id=\"263\"]Large language models[\/pb_glossary] can be incredibly helpful in both creating readable code and understanding code written by others.\r\n\r\nYou can paste in a snippet of code and ask the model to explain what it does, break it down line by line, and summarize its purpose in plain language. This is especially useful when working with obscure libraries or unfamiliar programming styles. Similar to pair-programming, using an LLM can save a lot of time when you get stuck or are having a hard time understanding how a piece of code works.\r\n\r\nUsing an LLM as a coding assistant for code generation can also help you to iterate quickly. You can ask it to write single functions or whole data processing scripts based on natural language descriptions of what you want to achieve. It can also generate boilerplate code, set up test cases, or help scaffold a new project. This makes prototyping much faster and lowers the barrier to entry for people who are newer to programming or working in unfamiliar languages. That said, generated code definitely needs review and testing, as the model might make assumptions or use outdated practices.\r\n\r\nWhen trying to write clear and readable code, it\u2019s good practice to follow norms and conventions. Programming languages and major libraries or frameworks all have their own conventions, and individual large software projects may have their own internal styles as well. When using GenAI tools to help write code, you\u2019ll need to be aware of the conventions and likely modify the generated output to match the style of your project.\r\n\r\nOne of the greatest benefits of open software is reuse. One author can create and maintain a library of code to solve a particular software challenge, and many other people can re-use that library. Over time improvements can be made to the library, and all of its users can benefit from the changes. Particularly in areas such as cybersecurity and cryptography, it\u2019s very important to use well established, thoroughly vetted software libraries, rather than creating your own or letting an LLM create one for you. LLMs are great at generating new code, but sometimes you will need to steer them towards reusing an existing library instead.\r\n
\r\n\r\n\r\n\r\n
\r\n
Dig Deeper<\/h5>\r\nTo learn more:\r\n
\"\"<\/td>\r\n<\/tr>\r\n<\/tbody>\r\n<\/table>\r\n<\/div>\r\n

Literate Programming<\/h2>\r\nClean, readable code is just the first step in increasing our transparency and reproducibility. Literate programming takes us to the next level.\r\n\r\nFormally introduced by Donald Knuth, literate programming is inspired by a shift in how one\u2019s code is communicated; the goal being to, as Knuth states:\r\n
\r\n
\r\n
\u201c[i]nstead of imagining that our main task is to instruct a computer<\/em> what to do, let us concentrate rather on explaining to human beings<\/em> what we want a computer to do\u2026 [achieved] \u2026 by considering programs to be works of literature.\u201d<\/blockquote>\r\n<\/div>\r\n
\r\n

Knuth, Donald E. (1984). \u201cLiterate Programming\u201d<\/a>. The Computer Journal<\/em>. 27: 97\u2013111.<\/p>\r\n<\/blockquote>\r\nCommon implementations of literate programming that you may have heard about include R Markdown and Jupyter Notebooks.\r\n

What is R?<\/strong><\/h3>\r\nR has taken academia by storm. R is a programming language that is becoming commonplace in many disciplines. R is open source and community developed. It is great for statistical analyses. It makes beautiful visualizations from your data. Thanks to community efforts it has add-ons that produce gorgeous documents, allowing you to write something once and export it to html, pdf, or Microsoft Word.\r\n

Is R the be-all and end-all?<\/strong><\/h3>\r\nNo. Open, reproducible work flows should be tool agnostic. R just happens to very accessible and well supported. And it is what we\u2019ll be referring to when we talk about scripted programming in this chapter. You\u2019ll find plenty of alternatives, and more about R, on the Additional Open Software<\/a> page!\r\n\r\n<\/div>\r\n

Example of Literate Programming<\/h2>\r\nThe following is an example of what literate programming looks like.\r\n\r\nFirst, we have a traditional output, a pdf, that we might be used to seeing; this includes some text and a few tables or graphs. We have no insights into how the data has been handled, and how the visualizations were derived (select the image to view the pdf). Sharing this pdf works well to communicate our findings, but does not enable others to see or reuse the details of our data manipulation.\r\n\r\n[caption id=\"attachment_187\" align=\"aligncenter\" width=\"482\"]\"\" Download PDF<\/a>[\/caption]\r\n\r\nSecondly, we have the underlying document that generated the above, written using R Markdown. It integrates the code used to generate the above document! If on a system using R, and the tools to interpret R Markdown, it can be used to generate the above document, making our work reproducible. Better still, this document is written in plain text, so it can be opened by virtually any text based program, making our work transparent; even without access to R, we can still read the below and understand how the processing was handled. It\u2019s also highly reusable: someone could easily perform an identical analysis on a different dataset, or change the plotting parameters to produce a different visualization.\r\n
---\r\ntitle: \"mtcars\"\r\noutput: pdf_document\r\n---\r\n```{r setup, include=FALSE}\r\nknitr::opts_chunk$set(echo = FALSE)\r\n```\r\nR Markdown documents allow us to interweave narrative text and R code. For more details on using R Markdown see <http:\/\/rmarkdown.rstudio.com>.\r\n\r\nR contains several datasets to allow a user to explore various features of the software before we have our own data to work with. One of these datasets is called mtcars.\r\n\r\nThe data, from 1974, details 10 aspects of design and performance for 32 car models.\r\n\r\nThe following is a summary of the data for a subset of the variables:\r\n\r\n```{r}\r\nsummary(mtcars[c(1:3,6)])\r\n```\r\nAnd here is a tabular view of the data for these same variables for all cars with V6 engine, sorted by increasing mpg\r\n\r\n```{r}\r\nlibrary(kableExtra) # load needed libraries\r\n\r\n# select and view subset of data in tabular format\r\nV6 <- mtcars[order(mtcars$mpg, decreasing = FALSE),] %>%\r\n  subset(cyl == 6)\r\nV6[c(1:3, 6)] %>%\r\n  kbl() %>%\r\n  kable_styling()  \r\n```\r\nWhat we really want to know though, is, is there a correlation between a car's weight, and it's MPG. Well, actually, being in Canada, we want to know this relation in KPG. So, first we'll add two columns to our data that contains the converted values (MPG to KPL and lbs to Kg, the latter rounded to the nearest whole number) and then we'll run a scatter plot to investigate.\r\n\r\n```{r}\r\nmwt <- round(mtcars$wt * 1000 * 0.45359237, digits = 0) # convert imperial to metric and round off\r\nkpl <- mtcars$mpg * 1.609 # convert imperial to metric\r\nmmtcars <- cbind(mtcars, mwt, kpl) # add metric data to existing data set\r\n\r\n# plot\r\nplot(mmtcars$kpl, mmtcars$mwt, xlab = \"Kilometres per Litre\", ylab = \"Weight in Kilograms\", col = \"#4682b4\", fg = \"#888888\", col.lab = \"#4682b4\", col.axis = \"#888888\", bty = \"n\")\r\n```<\/code><\/pre>\r\n\r\n
\r\n\r\n
\r\n
Test Your Knowledge<\/h5>\r\n[h5p id=\"23\"]<\/code>\r\n\r\n<\/div>\r\n
\r\n\r\n\r\n\r\n
\r\n
Dig Deeper<\/h5>\r\nTo learn more about literate programming and readable code, look into the following:\r\n
\"\"<\/td>\r\n<\/tr>\r\n<\/tbody>\r\n<\/table>\r\n<\/div>","rendered":"
As we mentioned in the first section, a key element of open software includes using tools that enable human and machine interpretable content so that even if a particular piece of software is no longer available, a human should still be able to understand what the intent of the code was.<\/p>\n
When we talk about open in the context of creating human and machine interpretable code, we\u2019re talking about organized, documented code supported through scripting and literate programming.<\/p>\n
Programs can be shared either as source code (as the programmer wrote it) or compiled (a format intended only for machine-reading, not to be read directly by people). Sharing a compiled program allows someone else to use it, but does not allow them to see the internals of how the program operates, or modify it to behave differently.<\/p>\n
Readable Code<\/h2>\n
It\u2019s all well and good if we make our code available by the ethos of Free and Open Source Software (FOSS) and engage in literate programming when compiling our data and outputs. But if the syntax and structure of our code are not clear, we are no more transparent than the black box of 0s and 1s we are trying to overcome.<\/p>\n
Writing clear code that a human can make sense of is critical for both transparency and reproducibility in the research life cycle.<\/p>\n
So, what does readable code look like? The following video Readable Code (3:59) from Khan Academy gives a pretty good overview of how code can be made more accessible to a human reader. Don\u2019t focus on the actual coding language but on the principles of making it readable.<\/p>\n