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

Exemplify more Carpentries-relevant code style tools #698

Open
wants to merge 3 commits into
base: gh-pages
from

Conversation

@katrinleinweber
Copy link
Contributor

katrinleinweber commented Nov 11, 2019

Since no Carpentries lesson teaches Perl, Ruby or focusses on HTML, how about mentioning tools that are relevant for our curriculum? These are suggestions which have been mentioned in a lesson, or its repository.

Related to datacarpentry/R-ecology-lesson#359, swcarpentry/shell-novice#239 & swcarpentry/r-novice-gapminder#529, and to #432.

Copy link
Member

munkm left a comment

I really like updating the style suggestions to what we teach in other carpentries lessons. I've made a few suggestions about the content. Let me know what you think.

Thank you for updating these! I think the learners will find them more useful in practice.

`htmltidy`, `perltidy`, `rubocop`, etc.) to enforce, if necessary
project convention that is governing, use code style tools (e.g.
`styleR` or `Code > Reformat` in RStudio,
or [`pep8` in Python](https://swcarpentry.github.io/python-novice-gapminder/18-style/index.html#follow-standard-python-style-in-your-code),

This comment has been minimized.

Copy link
@munkm

munkm Nov 18, 2019

Member

Since this particular section in the gapminder lesson mentions the google style guide for Python, it might be worth mentioning here too.

This comment has been minimized.

Copy link
@katrinleinweber

katrinleinweber Nov 19, 2019

Author Contributor

This is a good point, because the Google style guide recommends to use the "yapf auto-formatter". So, I suggest we either add a link to it to python-novice-gapminder/18-style and don't mention the particular tools here. Duplicating content across lessons is not a good idea, IMHO. How about 2e0f8b3 ?

_episodes/09-conflict.md Outdated Show resolved Hide resolved
project convention that is governing, use code style tools (e.g.
`styleR` or `Code > Reformat` in RStudio,
or [`pep8` in Python](https://swcarpentry.github.io/python-novice-gapminder/18-style/index.html#follow-standard-python-style-in-your-code),
[ShellCheck(.net)](http://swcarpentry.github.io/shell-novice/guide/#teaching-notes),

This comment has been minimized.

Copy link
@munkm

munkm Nov 18, 2019

Member

Since ShellCheck doesn't appear to be a style guide, I think it is misleading to include it in this list.

This comment has been minimized.

Copy link
@katrinleinweber

katrinleinweber Nov 19, 2019

Author Contributor

True, but this section is about "code style tools", not "style guides" ;-)

This comment has been minimized.

Copy link
@kekoziar

kekoziar Nov 29, 2019

Contributor

ShellCheck appears to be a debugger, not a code formatter/code style tool.

Co-Authored-By: Madicken Munk <madicken.munk@gmail.com>
katrinleinweber added a commit to katrinleinweber/python-novice-gapminder that referenced this pull request Nov 19, 2019
`htmltidy`, `perltidy`, `rubocop`, etc.) to enforce, if necessary
project convention that is governing, use code style tools (e.g.
`styleR` or `Code > Reformat` in RStudio,
or [the tools listed in our Python lesson](https://swcarpentry.github.io/python-novice-gapminder/18-style/index.html#follow-standard-python-style-in-your-code),

This comment has been minimized.

Copy link
@munkm

munkm Nov 19, 2019

Member
Suggested change
or [the tools listed in our Python lesson](https://swcarpentry.github.io/python-novice-gapminder/18-style/index.html#follow-standard-python-style-in-your-code),
or `pep8` or `the google style guide`, which are mentioned [in our Python lesson](https://swcarpentry.github.io/python-novice-gapminder/18-style/index.html#follow-standard-python-style-in-your-code),

This comment has been minimized.

Copy link
@munkm

munkm Nov 19, 2019

Member

I think it is better to explicitly list style guides like pep8 and the google style guide here. This change forces learners to click on the link to learn what Python style tools might be available to them, and I think that's not a good practice for the lesson.

This comment has been minimized.

Copy link
@katrinleinweber

katrinleinweber Nov 19, 2019

Author Contributor

Let's agree to disagree on this, again. I don't think avoiding-at-all-costs for learners or instructors to click on a link (only if they want to; not "forced"!), read elsewhere, then browse back to the lesson is worth:

  1. mixing tools and guides,
  2. duplicating names here that are less relevant than the link itself, and
  3. setting future maintainers up for needing to fix a mismatch of those names, if they ever update one side of this link.

I'll not invest any more time in this. Feel free to modify the PR as you find best. I'll focus on preparing to teach a workshop.

This comment has been minimized.

Copy link
@munkm

munkm Nov 19, 2019

Member

I agree that this will add some maintainer burden regarding your point (3), which does concern me. However, I think it's worth ensuring that the learner experience is smooth rather than that the maintainer experience is easier. In this particular case, the r and shell tools are clear and obvious in the text while the python tools are now obfuscated. I don't think that's particularly helpful to any learners that may be curious about the Python style tools.

Good luck teaching the workshop!

@maxim-belkin

This comment has been minimized.

Copy link
Contributor

maxim-belkin commented Nov 19, 2019

I'd like to weigh in here.

What I like about this PR

  • it refers to the tools that The Carpentries actually teach
  • it provides a suggestion how to share information in a project.

Where it could be improved

  • "Code -> Reformat Code" doesn't do much -- it seems that this is a code beautifier, not style-enforcer, like styleR or pep8 (btw, pep8 is both, a style guide and a tool that was recently renamed to pycodestyle). I think "Code -> Reformat Code" is from a different category of tools so shouldn't be listed.
  • linking to Python Novice Gapminder -- Imagine telling a story and saying "...like chickens in modern era, some creatures that you can read about in another book in middle age, and dinosaurs millions of years ago...". (weird example, I know). The point is -- the middle part doesn't make sense. If we're providing examples for R, Python, and Bash -- it only makes sense to do it for every tool. So, I think a specific Python tool (style guide enforcer) has to be listed.
  • Links. In general, I think links have to point to the home pages of the linked text. Links to our lessons should be preceded with a text that reads something like this You can learn more about these tools in our lessons on [Python](link), [R](link), and [Bash](link). But this is a separate sentence and the benefits of adding it have to be reviewed.
  • change ShellCheck.Net to ShellCheck

So, in summary, my suggestions are:

  • remove "Code -> Reformat Code"
  • list pycodestyle for Python
  • remove links to SWC lessons
  • if discussions of these tools in our lessons are significant -- consider adding links to these discussions in a separate sentence.

Great work y'all!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.