The Power of Code Snippets

How To Turn Your Code from Good to Great

The Pythonic Algorithm for Success
(CoverImage by WallPaperCave)

Contents

1. Introduction
2. R + RStudio
3. Python + VSCode
4. Conclusion
5. More Resources

1. Introduction

Modern day programmers write a lot of code. That’s part of the job. But one of the main principles of writing good code is the DRY principle: Don’t Repeat Yourself (see The DRY Principle: R Functions or The DRY Principle: Python Functions or Wikipedia or any number of other online sources). In essence, this principle effectively states that if you are going to write the same code twice, then don’t; instead, write the code in a function, then call the function twice.

There’s also another principle, which is equally if not more important: Document Your Work. For this, function docstrings are extremely helpful. Basically, you want to write your code for someone else (even if that someone else is the future version of you…), so that they can understand your code better. Here, you want to explain why your code is doing what it is doing (the reader can see what the code is doing by simply reading the code itself). Such as if there is some complicated logic, or to handle a quirk in the data, then it’s best to write a docstring. But don’t go overboard though! There are many reasons why too much documentation can be a bad thing (such as How to Comment Your Code Like a Pro: Best Practices and Good Habits and Putting Comments in Code: The Good, the Bad, and the Ugly).

It is the intersection of these two principles that gives rise to the use of a fantastic thing in the world of programming: Code Snippets. These snippets are effectively ‘saved chunks of code’, which can allow you to speed up the implementation of your code, and the overall readability of your code. And ultimately, will turn your code from Good to Great.

When approaching this from a Data Science perspective, I will focus on the two most popular coding languages in this field, and the popular IDE for each of them: R + RStudio and Python + VSCode.

2. R + RStudio

R Code Snippet
(Image by Kun Ren on RenKun.me)

To start off with, here’s some good sources for using docstrings and Code Snippets in RStudio:

• The tidyverse Style Guide: Documentation
• Introduction to docstrings
• Is there a sensible way to do something like docstrings in R?
• docstring package
• Common R code snippets
• Code Snippets in the RStudio IDE
• How to use RStudio code snippets
• 4 ways to be more efficient using RStudio’s Code Snippets, with 11 ready to use examples

To find the Code Snippets for RStudio, just navigate to: Tools > Global Options > Code > Editing > Edit Snippets.

Finding Code Snippets
(image by Author)

There, you’ll find a whole bunch of Snippets which have been provided already by the RStudio team. Including one for writing functions:

R Snippet Basic
(Part of: chrimaho/code-snippets)

But I think that we can do better than that.

R Snippet Extended
(Part of: chrimaho/code-snippets)

This function will follow the standard syntax for doing docstrings. Including using the special comment characters #' at the start of the line, and various @ attributes. See above resources for why these are important and how to use them.

By using this code snippet, you will be able to:

1. Quickly and easily implement your new function.
2. Effectively ‘document as you write’ your function as you write it for the first time; as opposed to needing to come back and ‘re-write’ your docstring sometime after you have written your function for the first time.
3. Easily tab through the different sections of the function, and fill in different sections at the same time, thanks to the use of ${1:FunctionName} appearing in different locations.
4. Return a ready-to-run, and well-documented function in merely a matter of minutes.

But you don’t only need to do this for function declarations. You can also add various headers and sections to your file.

!!EASTER EGG!!

If you end the comment line with four identical characters (like #### or ----), then RStudio will add that line to the Document Outline panel! Which makes for awesome document navigation. But you can take this one step further. If you add multiple # characters at the beginning of the line, then you can automatically indent the Document Outline headers! This will make your life amazing.

Document Panel Amazingness
(image by Author)

If you wanted the raw files for these Snippets, check them out here:

Snippets_Input.txt

Snippets_Output.R

3. Python + VSCode

Python Code Snippet
(Image by Chris Ried on UnSplash)

Same as before, let’s start off with some good resources for using Python docstrings and code snippets in VSCode:

• Snippets in Visual Studio Code
• PEP 257 — Docstring Conventions
• Python Docstrings
• What is the standard Python docstring format?
• The docstrings main formats
• 30 Helpful Python Snippets That You Can Learn in 30 Seconds or Less
• 22 Python Code Snippets for Everyday Problems
• 22 Code Snippets That Every Python Programmer Must Learn

To find the Code Snippets for VSCode, you will need to use the Command Palette: press ctrl+shift+p, type snip, select Preferences: Configure User Snippets, then open the snippets.code-snippets file. Here, you can configure any user snippets you want. This file is fundamentally a JSON file, so you should follow the syntax convention for that.

Similar to RStudio, VSCode has some defaults. Such as:

Python Snippet Basic
(Part of: chrimaho/code-snippets)

However, we know that there is a better way to do this.

Python Snippet Extended
(Part of: chrimaho/code-snippets)

The benefits of this snippet in VSCode are quite similar to the RStudio benefits:

1. It’s quick,
2. It’s effective,
3. It’s easy,
4. It’s ready-to-go.

!!EASTER EGG!!

VSCode renders the docstrings in Markdown format! Meaning that you are able to input Headings, code chunks, italics, bold, pretty much any Markdown format that you want! This may break the regular docstring conventions (eg. Numpy, Google, Sphinx). But for me, that’s okay. It makes my VSCode environment look professional. You’re welcome.

Docstrings with Markdown Format
(image by Author)

If you wanted the raw files for these Snippets, check them out here:

Snippets_Input.code-snippets

Snippets_Output.py

4. Conclusion

Snippets are a fantastic way to quickly and easily build your code in a consistent and aesthetic manner. They are highly configurable and they add a substantial amount of value and efficiency to your coding. By using snippets, your future you will be thanking you. Trust me.

5. More Resources

• 10 Amazing Tips and Tricks for Data Scientists: Some more helpful code snippets in R and Python
• 10 Tips and Tricks for Data Scientists: Helpful code snippets in R and Python
• 5 Powerful Python and R Tricks for Data Scientist: Helpful code snippets in R and Pythons
• 10 Real-World Tips and Tricks That Data Scientists Would Love: Some more helpful code snippets in Python, R, and more

Plenty More Programming
(Image by Irvan Smith on UnSplash)