R Dev Guide: Document VS Code and Positron settings for working on R sources

[hturner]

As discussed in #104, an.editorconfig that sets appropriate settings in other IDEs will result in incorrect indentation for C files with VS Code or Positron. So for the moment, I think it is best to advise people to use the IDE settings, rather than an .editorconfig.

We can add this in a new "IDE Setup" chapter of the R Dev Guide. I have partial settings below, we can compare this to the .editorconfig in #104 to develop more complete settings.

Note that using either the .editorconfig or the settings would be fine if you never work with C files. If an .editorconfig gets added to the R sources, we may want to add a note saying how to ignore it (if EditorConfig for VS Code extension installed, can disable for the current workspace via the Extensions panel).

VS Code

Here the settings for C and R files are the same. Ideally C would be different: every 8 spaces in an indent would be replaced by a tab (https://bugs.r-project.org/show_bug.cgi?id=18757#c1). I could not find a VS Code extension that does this - maybe we could write one??

{
  // Editor settings for C files
  // Cannot set to auto replace 8 spaces with tab (https://github.com/Microsoft/vscode/issues/ #42740, #5394)
  "[c]": {
    "editor.indentSize": 4, // indent 4 spaces each indent level
    "editor.tabSize": 8, // display 8 spaces as a tab
    "editor.insertSpaces": true, // need this to get indent size 4, else uses tabs to indent
    "editor.detectIndentation": false, // if set true, detects settings as above from the code in the file
  },
  // Editor settings for R files
  "[r]": {
    "editor.indentSize": 4,
    "editor.tabSize": 8,
    "editor.insertSpaces": true,
    "editor.detectIndentation": false
  },
  // Turn off linting for R files 
  "r.lsp.diagnostics": false
}

Positron

Same as VS Code but don't need r.lsp.diagnostics": false as not using R language server.

[DavisVaughan]

Merging with my own set up from a previous r-dev-day, I get:

{
  // Editor settings for C files
  // Cannot set to auto replace 8 spaces with tab (https://github.com/Microsoft/vscode/issues/ #42740, #5394)
  "[c]": {
    // An indent is 4 spaces
    "editor.indentSize": 4,
    // But display 8 spaces as a single tab
    "editor.tabSize": 8,
    // Need this to get indent size 4, else uses tabs to indent
    "editor.insertSpaces": true,
    // If set true, detects settings from the code in the file
    "editor.detectIndentation": false,
  },
  // Editor settings for R files
  "[r]": {
    "editor.indentSize": 4,
    "editor.tabSize": 8,
    "editor.insertSpaces": true,
    "editor.detectIndentation": false
  },
  // There isn't a formatter that works great with R itself
  "editor.formatOnSave": false,
  // Shows the difference between 4 spaces and 8 spaces (tab) visually
  "editor.renderWhitespace": "all",
  // Show whitespace changes in the diff editor to help us get it right
  "diffEditor.ignoreTrimWhitespace": false,
  // Trim trailing whitespace after a line, or on a blank line.
  // You may need to turn this off in some files where historically
  // trailing whitespace has not been trimmed, but otherwise it is
  // good practice to trim it.
  "files.trimTrailingWhitespace": true,
  // Turn off {languageserver} linting for R files
  "r.lsp.diagnostics": false
}

[kevinushey]

For VSCode / Positron users, the clangd extension can be useful for C editor tools and diagnostics in R. https://open-vsx.org/vscode/item?itemName=llvm-vs-code-extensions.vscode-clangd. You can teach clangd how to parse R's sources by creating a file compile_flags.txt at the project root with the contents:

-Isrc/include
-DR_INLINE=inline

Indeed, this would work with any editor that's using clangd as a language server. It's not perfect as it'll recommend the Rf_ prefixed variants for completions rather than the macro-defined shorter variants, but it's still helpful in other contexts.

This is a work-in-progress, but I'm also putting together a collection of VSCode tasks / launch configurations that can make it easier to configure and build R as well.

https://github.com/kevinushey/r-source/tree/trunk-kevin/.vscode

Positron is also capable of providing R editor support in the R files used in R's sources, which is incredibly nice.

[SaranjeetKaur]

Started a Positron extension during R dev day at RSECon25, University of Warwick

In progress PR here: r-devel/auto-tabs#1

[hturner]

I separated development of the Positron extension into a new issue: #128

[DavisVaughan]

Here's another idea, which I am well aware could be considered a nuclear option by some.

Maybe we should acknowledge that tools simply work better with a simpler indentation scheme and switch to 4 spaces for an indent within the C source, all encapsulated within a single commit, combined with usage of a .git-blame-ignore-revs file containing the SHA of that commit. That allows git blame and GitHub's blame UI to "skip over" that purely formatting commit when reviewing code history. We have used it with great success with Air, and in Quarto as well.

https://docs.github.com/en/repositories/working-with-files/using-files/viewing-and-understanding-files#ignore-commits-in-the-blame-view

This is related to conversations both @hfrick and @lionel- have been having with R Core members.

I would be fully in support of this as it gets us one step closer to being able to use clangd / clang-format as a formatter for the C source, which effectively every IDE supports, and allows us to provide a much improved user experience for both new and experienced contributors.