code.qmd

# Code Style {#sec-code-style}

```{r}
#| eval: true 
#| echo: false 
#| include: false
source("_common.R")
```


```{r}
#| label: co_box_dev
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "y", 
  header = "Caution",
  contents = "The contents for section are being revised. Thank you for your patience."
)
```

:::: {.callout-tip collapse='true' appearance='default'}

## [Accessing applications]{style='font-weight: bold; font-size: 1.15em;'}

::: {style='font-size: 0.95em; color: #282b2d;'}

I've created the [`shinypak` R package](https://mjfrigaard.github.io/shinypak/) In an effort to make each section accessible and easy to follow:
  
Install `shinypak` using `pak` (or `remotes`):

```{r}
#| code-fold: false 
#| message: false
#| warning: false
#| eval: false
# install.packages('pak')
pak::pak('mjfrigaard/shinypak')
```

Review the chapters in each section:
  
```{r}
#| code-fold: false 
#| message: false
#| warning: false
#| collapse: true
library(shinypak)
list_apps(regex = '^21')
```

Launch an app with `launch()`

```{r}
#| code-fold: false 
#| eval: false
launch(app = "21_style")
```

Download an app with `get_app()`

```{r}
#| code-fold: false 
#| eval: false
get_app(app = "21_style")
```

::: 

::::


> ["*We're in the business of keystrokes and neurons*"]{style="font-size: 1.25em; font-weight: bold; font-style: italic;"}

During development, it can be challenging to keep the code in your app-package clean and perfectly formatted. Fortunately, the R ecosystem has some excellent tools for making your code functional and easy to read.

## Code style and formatting

The [`lintr`](https://lintr.r-lib.org/) and [`styler`](https://styler.r-lib.org/) packages in R serve related but distinct purposes and have different focuses in their functionality. The primary difference between `lintr` and `styler` is that `styler` can automatically fix any stylistic issues it identifies in your code (rather than just reporting them). 

```{r}
#| label: git_box_21_style
#| echo: false
#| results: asis
#| eval: true
git_margin_box(
  contents = "launch",
  fig_pw = '75%', 
  branch = "21_style", 
  repo = 'sap')
```

### `lintr` {#sec-lintr}

`lintr` is a static code analysis tool used to identify syntax errors, semantic issues, and violations of stylistic guidelines in your code. The package contains a list of 'linters' for various potential problems and can be customized according to your needs. lintr is designed to help improve your code's quality and readability by generating reports in the 'markers' pane. Running `lintr` won't automatically correct the identified issues (you'll need to fix the linting issues it reports manually). 


### `styler` {#sec-code-style-styler}

On the other hand, the purpose of `styler` is to ensure consistency in the code formatting, which is crucial if you're working in a team or contributing to open-source projects (like `tidyverse` packages). The `styler` package will change your code's format according to specified style guidelines. These changes include indentation, spaces, and line breaks that adhere to your style guidelines. 

While there is some overlap (both packages can help enforce coding style guidelines), `lintr` is a more general tool for code quality, spotting potential issues and bugs. At the same time, `styler` focuses on code formatting and can automatically apply fixes. Many developers find combining both can help catch potential issues and ensure a consistent, readable coding style.

## Checking your code 

I've [previously mentioned](@sec-dev-check) running `devtools::check()` can be overkill for your app-package (especially if it's not destined for CRAN). A nice alternative to `check()` is the [`goodpractice` package.](https://mangothecat.github.io/goodpractice/).

`goodpractice::gp()` inspects your package and prints any areas that might need 'good practice' advice: 

```{r}
#| eval: false
#| code-fold: false
library(goodpractice)
pkg_checks <- gp(path = ".")
pkg_checks
```


```{verbatim}
Preparing: description
Preparing: lintr
  |====================================================================| 100%
Preparing: namespace
Preparing: rcmdcheck
── GP sap ───────────────────────────────────────────────────────

It is good practice to

  ✖ add a "URL" field to DESCRIPTION. It helps users find information about your
    package online. If your package does not have a homepage, add an URL to 
    GitHub, or the CRAN package package page.
  ✖ add a "BugReports" field to DESCRIPTION, and point it to a bug tracker. 
    Many online code hosting services provide bug trackers for free, 
    https://github.com, https://gitlab.com, etc.
  ✖ avoid long code lines, it is bad for readability. Also, many people prefer 
    editor windows that are about 80 characters wide. Try make your lines 
    shorter than 80 characters

    data-raw/tidy_movies.R:49:81
    R/data.R:4:81
    R/data.R:7:81
    R/data.R:17:81
    R/data.R:21:81
    ... and 13 more lines

  ✖ not import packages as a whole, as this can cause name clashes between the 
    imported packages. Instead, import only the specific functions you need.
  ✖ fix this R CMD check NOTE: display_type: no visible binding for global 
    variable
    ‘.rs.invokeShinyPaneViewer’ display_type: no visible binding for global 
    variable
    ‘.rs.invokeShinyWindowExternal’ display_type: no visible binding for global
    variable
    ‘.rs.invokeShinyWindowViewer’ mod_scatter_display_server : <anonymous>: no 
    visible binding for global
    variable ‘movies’ Undefined global functions or variables: 
    .rs.invokeShinyPaneViewer 
    .rs.invokeShinyWindowExternal 
    .rs.invokeShinyWindowViewer 
    movies
```

We can also check specific components of our package by looking up the available checks in `all_checks()`:

```{r}
#| eval: false
#| code-fold: false
grep("import", x = all_checks(), value = TRUE)
```

```{bash}
#| eval: false
#| code-fold: false
[1] "no_import_package_as_a_whole"                 
[2] "rcmdcheck_undeclared_imports"                 
[3] "rcmdcheck_imports_not_imported_from"          
[4] "rcmdcheck_depends_not_imported_from"          
[5] "rcmdcheck_triple_colon_imported_objects_exist"
[6] "rcmdcheck_unexported_base_objects_imported"   
[7] "rcmdcheck_unexported_objects_imported"        
[8] "rcmdcheck_empty_importfrom_in_namespace"  
```

All of the checks with the `rcmdcheck_` prefix are part of the `R CMD check` diagnostic, but `goodpractice` comes with other checks that are good practices (even if you're not submitting your package to CRAN). 

For example, `no_import_package_as_a_whole` checks the practice we covered in [managing imports](#sec-depends-imports). If we pass the `no_import_package_as_a_whole` check as a character vector to the `checks` argument: 

```{r}
#| eval: false
#| code-fold: false
gp(path = ".", checks = 'no_import_package_as_a_whole')
```

Only this check is performed:

```{bash}
#| eval: false
#| code-fold: false
── GP sap ───────────────────────────────────────────────────

It is good practice to

  ✖ not import packages as a whole, as this can cause name clashes between
    the imported packages. Instead, import only the specific functions you need.

───────────────────────────────────────────────────────────────────
```

## Recap 

This chapter covered an introduction to some tools and practices for improving and maintaining the quality of the code in your app-package. Maintaining code style and standards (`lintr` and `styler`) and performing thorough checks to adhere to best practices (`goodpractice`) will ensure efficient and reliable development and deployment for your app.

```{r}
#| label: co_box_recap
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "b",
  header = "Code tools recap",
  look = "default", hsize = "1.10", size = "1.05",
  contents = "
  This chapter covered: 
  
**Code Linting and Styling**:

- `lintr` is used for checking the code for potential errors and style issues\n
  - Can help in identifying syntactical and stylistic problems that might lead to code inefficiency or errors\n
  - Linters are instrumental in enforcing coding standards and ensuring consistency across the codebase
  
- `styler` is used to automatically style the R code in your app-package\n
    - `styler` will format R code according to specified style guidelines, ensuring that the code is not only consistent in its look but also adheres to best practices\n
  - Automating styling can save time and reduces manual effort in code formatting\n

**Managing Dependencies**:

- The `attachment` package helps in managing these dependencies by automatically listing and updating the packages used in your app-package
  - `att_amend_desc` scans the code and identifies all package dependencies\n   
  - managing dependencies ensures reproducibility and ease of package installation\n
  
- `desc` assists in handling the `DESCRIPTION` file in your app-package\n
    - provides tools for reading, writing, and modifying the `DESCRIPTION` files
  
**Code Checks**:

- `goodpractice` is designed to help ensure best practices in R coding and package development are adhered to in your app-package\n
  - `goodpractice::gp()` performs a comprehensive analysis of the code (beyond `devtools::check()`) and checks for various potential issues like code complexity, redundancy, adherence to coding standards, etc\n 
  - Offers suggestions for improvements, making it a helpful tool for quality assurance in package development\n
  ", 
  fold = FALSE
)
```