devtools::install_github("lorenzwalthert/strcode")

A concept for code structuring

The main feature of the package is its function to insert code breaks. These are helpful in breaking the code down into smaller sections. We suggest three levels of granularity for code structuring, wherein higher-level blocks can contain lower-level blocks:

You can notice from the above that:

• The number of #’s used in front of the break character (___, ..., . .) correspond to the level of granularity for a code separator.
• The breaks characters ___, ..., . . were chosen such that they reflect the level of granularity, namely ___ has a much higher visual density than . ..
• Each block has an (optional) short title on what that block is about.

Every title line ends with ####. Therefore, the titles are recognized by RStudio as sections. This has the advantage that you can get a quick summary of your code in RStudio’s code pane as depicted below.

In addition, it means that you can fold sections as you can fold function declarations or if statements.

The package strcode provides an RStudio Add-in to insert each of the three separators presented above – with a single click. To invoke the Add-in, simply click on the button Addins in your RStudio Window and select the separator you want to insert.

By default, a Shiny Gadget will open in the viewer pane where you can also specify the title of the section (optional) and whether or not a unique identifier/anchor should be added to the section (see below).

If you prefer to insert the separator without the Shiny Gadget, you can change the option strcode$insert_with_shiny to FALSE which will only insert the break. The separators all have length 80. The value is looked up in the global option strcode$char_length and can therefore be changed by the user as well. The length of separators is thought to correspond to the character width limit you use.

Anchoring sections

Sometimes it is required to refer to a code section, which can be done by a title. A better way, however, is to use a unique hash sequence – let us call it a code anchor – to create an arguably unique reference to that section. A code anchor in strcode is enclosed by #< and ># so all anchors can be found using regular expressions. You can add section breaks that include a hash. Simply tick the box when you insert the break via the Shiny Gadget. The outcome might look like this

Summarizing code

Once code has been structured with the separators introduced above, it can easily be summarized in a compact form. This is particularly handy when the code base is large, when a lot of people work on the code or when new people join a project. The function sum_str is designed for the purpose of extracting separators and respective comments, in order to provide high level code summaries. Thanks to RStudio’s API, you can even create summaries of the file you are working on, simply by typing sum_str() in the console.

The outcome might look like the following:

sum_str is highly customizable and flexible, with a host of options. For example, you can specify to omit level 3 or level 2 sections in the summary, summarizing multiple files at once, writing the summaries to a file and more.

Insert a code anchor

Code anchors might prove helpful in other situations where one wants to anchor a single line. That is also possible with strcode. An example of a code anchor is the following:

The hash sequences in strcode are produced with the R package digest.

To wrap it up, strcode tries to make structuring code easy and fun while keeping things simple. Give it a go. Feedback to the package is most welcome. If you find any bugs (in particular in sum_str) or if you have any suggestions for extensions of the package, feel free to open an issue on the GitHub repo of the package.

Appendix

As an appendix to this post, I would like to give a real-world example of how using strcode can improve the legibility of code.