README.md

In INWT/INWTUtils: Utility functions used by INWT

INWTUtils

This repository contains a package which provides utility functions used by the INWT Statistics GmbH. This includes amongst others functions to check code for violations of style conventions and to keep the searchpath clean. In addition, an example R script is included.

Checking code style with INWTUtils

Overview

This vignette describes how to check your code files for a good style with checkStyle (a wrapper for the lint function of the lintr package). The function is tailored to the usage at the INWT Statistics company but can by applied in other contexts without any disadvantages.

For several so-called lints the function checks if they appear in the code. In this context, lints are (mostly small) violations of style rules, e.g., missing spaces around operators, double spaces, very long lines or trailing blank lines. A function checking a specific lint is called linter function. The section "Included linters" gives more information about the set of tested lints.

Why should you watch your style?

Your code may be robust and fast in spite of a bad style. But a good style makes your code more beautiful and easier to read -- especially for others. Adapting a consistent style within a team helps to find your way around in the code written by someone else.

It's never to late to adapt a good coding style -- and never to early.

How to use checkStyle

checkStyle can be applied to one or more files. If you don't add any other argument, the default set of linters is used as returned by the function selectLinters. To demonstrate the usage, we first create two files with examples for bad style:

writeLines(c("# This is an example for bad style",
             "x = 1+2",
             "# A comment with  double  spaces",
             ""),
           con = "badStyle1.R")
writeLines(c("# This is a second example   ",
             "z<-c(1,2)"),
           con = "badStyle2.R")

How many violations of common style conventions do you see? checkStyle may find some more:

checkStyle(files = c("badStyle1.R", "badStyle2.R"))

A new tab opens in RStudio which lists all lints found in the checked files. It contains the full filepaths and a list with line numbers and lints for each file. You can start to edit the code and repeat the check until the opened tab remains empty.

If you want to customize the set of used linters, there are three possibilities:

• Specify a file type with the type argument
• Exclude linters with the excludeLinters argument
• Add more linters with the addLinters argument

These arguments are passed to selectLinters and change the set of linters that the function returns.

Specifying a file type via the type argument adds some linters to the set of used linters. You can choose between scripts (type = "script") or files with package functions (type = "pkgFuns"). Or you can just ignore the argument.

excludeLinters just needs a vector or list with names of the linters you want to exclude. addLinters needs a bit more: a named vector or named list of linters. How you choose the exact names doesn't play a role, but the values have to be linter functions from an attached package.

For example:

checkStyle(files = c("badStyle1.R", "badStyle2.R"),
           type = "script",
           excludeLinters = c("object_length_linter",
                              "function_argument_linter"),
           addLinters = list(setwd_linter = setwd_linter,
                             a = source_linter))

Included linters

The following linters are used by default:

• function_argument_linter

• assignment_linter

• commas_linter

• double_space_linter

• infix_spaces_linter

• internal_function_linter

• line_length_linter

• whitespace_linter

• object_length_linter

• sapply_linter

• spaces_left_parentheses_linter

• trailing_blank_lines_linter

• trailing_whitespaces_linter

If type = "script", no linters are added at the moment.

If type = "pkgFuns", the following linters are added:

• setwd_linter

• source_linter

• options_linter

The following linters stem from the INWTUtils package:

function_argument_linter checks if arguments without default value are listed before arguments with default value in function definitions.

double_space_linter checks for double empty spaces.

sapply_linter checks for use of the sapply function. Since sapply_linter does automatic simplification, you do not have full control over the output format. If the input changes, this can have unexpected effects.

setwd_linter, source_linter, and options_linter check for setwd, source resp. options statements because they can cause side effects when used in functions.

trailing_whitespaces_linter looks for superfluous whitespaces at the end of a line. [^a]

The remaining linters are taken from the lintr package. Details can be found via ?lintr::linters.

Exclude lines from checking

Sometimes you may want to exclude specific lines from the check because the found lint cannot be removed for some reason. You achieve this by adding the nolint commands into the file to be checked (see also ?lintr::exclude):

# nolint start
x <- c(1,2) # This line will be excluded from the checks
# nolint end
y <- c(3, 4) # This line won't be excluded anymore.

[^a]: This linter is very similar to trailing_whitespace_linter from the lintr package, but it takes a special case into account: If you insert the pipe operator %>% from the dplyr package using the shortcut Ctrl + Shift + m, a whitespace is inserted behind it per default. These whitespaces are not detected by trailing_whitespaces_linter because it would lead to many annoying alarms.

INWT/INWTUtils documentation built on May 22, 2024, 4:45 p.m.