Writing Code

Jon Reades & Fulvio Lopane

Three Phases of Coding

  1. Managing it
  2. Documenting it
  3. Writing it

Notice that writing comes last.

Managing Code

Git

Version control allows us to:

  1. Track changes to files with a high level of detail using commit.
  2. push these changes out to others.
  3. pull down changes made by others.
  4. merge and resolve conflicting changes.
  5. Create a tag when a ‘milestones’ is reached.
  6. Create a branch to add a feature.
  7. Retrieve specific versions or branches with a checkout.

GitHub

Git is distributed, meaning that every computer is a potential server and a potential authority. Result: commits on a plane!

But how do people find and access your code if your ‘server’ is a home machine that goes to sleep at night? Result: GitHub.

GitHub is ‘just’ a very large Git server with a lot of nice web-friendly features tacked on: create a web site, issue/bug tracking, promote your project…

Git+GitHub is for… anything!

Oh My Git!

Documenting Code

Markdown is intended to:

  • Make it easy to write and format text (headings, tables, bold, italics…).
  • Make it easy to embed rich media (video, images).
  • Make it easy to take this simply-formatted text and turn it into something useful (a web site, journal article, documentation…).

Additional Stylings

For those who know how to do it, you can also insert bits of real HTML and CSS (the ‘languages’ of web sites) as well.

This content has HTML formatting attached.

Why Use It?

The features that make it easy to use have real advantages for you:

  1. You will spend less time wrestling with Microsoft Word and its formatting; this means that…
  2. You will spend more time focussing on the important stuff: writing and coding!
  3. You will be able to combine Code and Documentation easily because Python/R and Markdown all coexist happily on GitHub.

Markdown Examples

See CommonMark and the Markdown Guide for more :

Format Output
Plain text… Plain text
## A Large Heading

A Large Heading

### A Medium Heading

A Medium Heading

- A list
- More list
  • A list
  • More list
1. An ordered list
2. More ordered list
  1. An ordered list
  2. More ordered list
[A link](http://casa.ucl.ac.uk) A link
Format Output
![Alt Text](casa_logo.jpg)
`A code snippet` A code snippet
```python
A block of Python code
``` 		A block of Python code

More Markdown…

Here are some more resources:

And once you’re ready to get ‘serious’, check out this tutorial on Sustainable Authorship in Plain Text using Pandoc and Markdown from The Programming Historian! That’s what actually underpins Knitr and Quarto, but you can do so much more…

Literate Programming

Ideally, we want to write code in ways that are ‘literate’.

The best programs are written so that computing machines can perform them quickly and so that human beings can understand them clearly. A programmer is ideally an essayist who works with traditional aesthetic and literary forms as well as mathematical concepts, to communicate the way that an algorithm works and to convince a reader that the results will be correct.

– Donald Knuth, Selected Papers on Computer Science

Key Tenets

What we want:

  1. Weaving: the code and its documentation are together in one file.
  2. Tangling: the code can be run directly from this file.

Why do we want this?

Jupyter(Lab) & Notebooks

Modern Browser + Jupyter == Tangled, Woven code in (m)any languages

Including maths:

\[ f(a) = \frac{1}{2\pi i} \oint_{\gamma} \frac{f(z)}{z-a} dz \]

JupyterLab + Python

All Kinds of Features

JupyterLab is basically a web application:

JupyterLab Uses Markdown

And so Does Quarto

Quarto is intended to:

  • Extend power of RMarkdown/knitr to all languages
  • Make it easy to create web sites, documents, and articles.
  • Make it easy to integrate code with text and images.

> This whole course, including this presentation, was written in Quarto.

Recap

  1. With Git + GitHub we have a way to ‘version’ text, code, images, etc. and distribute them online via both a browser and the command line.
  2. With Markdown we have a way to easily produce content (essays, documentation, web sites, presentations) and convert or distribute it via both a browser and the commenad line.
  3. With JupyterLab and Quarto we have ways to write code and documentation in an ‘woven’ manner.
  4. But all of this is irrelevant if you can’t communicate clearly.

Collectively, this constitutes sustainable authorship of code and ‘documentation’ in the broadest sense.

Resources

Writing Code • Jon Reades & Fulvio Lopane