Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document coding style used by R Core #133

Open
5 tasks done
hturner opened this issue Apr 6, 2023 · 6 comments · May be fixed by #216
Open
5 tasks done

Document coding style used by R Core #133

hturner opened this issue Apr 6, 2023 · 6 comments · May be fixed by #216

Comments

@hturner
Copy link
Member

hturner commented Apr 6, 2023

Is your feature request related to a problem? Please describe.
Contributors should be aware of the style typically used by R Core, so that R Core can focus on the code and not style issues when reviewing patches. Questions about style have come up on the Slack and I have also given feedback about this when reviewing patches before submission to Bugzilla.

Describe the solution you'd like
A new chapter/section on style. There is a little about R coding standards in the R-internals manual, e.g. using an indentation of 4 spaces in R and C code. Other style points I'm not sure are documented anywhere but I think are generally followed:

  • spaces after commas and either side of operators
  • <- rather than = for assignment
  • " rather than ' for quoting text
  • TRUE and FALSE not T and F
  • lines no longer than 80 characters

We could work through https://style.tidyverse.org/ to check what is common to base R. @mmaechler has also given talks about style and may know if there is another reference we should use.

Describe alternatives you've considered
N/A

Additional context
N/A

@hturner
Copy link
Member Author

hturner commented Apr 6, 2023

Perhaps we can recommend use of lintr cc @MichaelChirico.

@mmaechler
Copy link
Contributor

In all my talks on the issue, I had emphasized that humans can much better format code than algorithms.
(and sometimes I add .. at most half jokingly): If you don't want to get replaced by a robot, don't behave like one ..

@MichaelChirico
Copy link
Contributor

more than happy to collaborate developing linters specific to base R.

it really is an unfortunate experience to have a patch delayed due to stylistic issues -- having linters in place to at least cover some "don'ts" while leaving the "dos" more up to human judgment is certainly doable.

@itsdebartha
Copy link
Contributor

itsdebartha commented Apr 6, 2023

@hturner Can we make a task list for this issue to keep track of things being committed in the new chapter and the things that still need to be added?

@hturner
Copy link
Member Author

hturner commented Apr 14, 2023

@itsdebartha I updated my comment with an initial checklist. Meanwhile I re-discovered this vignette: https://cran.r-project.org/web/packages/rockchalk/vignettes/Rstyle.pdf, which gives guidance on style based on studying the source code of R and CRAN packages, along with an SEA score ("Subjective and completely unscientific personal Estimate
of Agreement." 😄). The SEA score gives an indication of how consistently that style is used in the R codebase. Probably we should document/add to the linter styles with an SEA > 0.9 or thereabouts.

Since this issue was motivated by a question on the R Contributor Slack about indentation style for C, I have done a little more digging. The R coding standards recommend to set the c-default-style in Emacs to "bsd", which implements the Allman style (https://www.gnu.org/software/emacs/manual/html_node/ccmode/Built_002din-Styles.html). However, this is not used consistently in the R code base, e.g.

(See Indentation Styles). So all we can say is that the C code in R follows the GNU coding standards for C code in that the open-brace that starts the body of a C function should be in column one.

Indentation in R code is similarly inconsistent. If we print()/View() an R function it is formatted in Stroustrup style, but I don't think that is commonly used by R developers - more in base R than elsewhere, but not enough to recommend it. I think K&R is more commonly used, often with the variation of having the opening brace for a function on the same line as function(), so I would recommend that if anything.

@jyoti-bhogal
Copy link

jyoti-bhogal commented Sep 5, 2024

Discussed a bit about this issue during the R Development Hackathon at RSECon24. I would be happy to contribute a chapter for this as discussed with @hturner and @SaranjeetKaur.

@SaranjeetKaur SaranjeetKaur linked a pull request Dec 4, 2024 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants