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

Extended section on tooling #50

Closed
wants to merge 3 commits into from
Closed

Conversation

metasim
Copy link

@metasim metasim commented Jul 8, 2020

Addition of content from Slack conversation.

Addition of content from Slack conversation.
@metasim
Copy link
Author

metasim commented Jul 8, 2020

Wasn't quite sure where it should go, but fodder for discussion.

@metasim
Copy link
Author

metasim commented Sep 15, 2020

@amontalenti Ping :)

@amontalenti
Copy link
Owner

Thanks for the ping/reminder here. Just got busy. Will tackle this week, I hope!

@amontalenti
Copy link
Owner

amontalenti commented Sep 20, 2020

Hey @metasim, thanks again for the ping here. So, good news and bad news.

The good news is that I made a couple of commits (dc84384, a31bdcb) on this branch after reviewing this contribution based on our Slack conversation. I basically did copy edits, clarifications, addition of relevant hyperlinks, and so on. You can see the finished result here:

https://github.com/amontalenti/elements-of-python-style/blob/a31bdcbd67b853cbbef6493e53218e5e88253ff9/README.md#standard-tools-and-project-structure

That's the good news. The bad news is, I don't think I'm ready to merge this just yet.

When I incorporated this in and then re-read the style guide, I noticed a couple of things:

  1. This section is much wordier than the other sections.
  2. Some pieces of this section feel less "timeless" than other sections to me.
  3. Some of it seems to veer outside of "style" and feels a bit more like a tutorial on "good tools to use"; I recognize that often which tools to use is a matter of style, so this might be a distinction without difference, but, I'm not sure yet.
  4. Arguably the "historical commentary" should be cut altogether, even though it is interesting.

I think you'll also find if you read the style guide top-to-bottom, it isn't clear whether these sections "fit" perfectly just yet. Perhaps I need to take a pass at them to remove words and move them more into the punchy style of the other sections. I also don't love the idea of going on and on for sections at a time without any code examples to "break up the wall of text" (as happens in the top half of the document prior to this addition).

In any case, I'm certain something from this section will make its way into the mainline, I just would like to "sleep on it" a bit. Let me know what you think after reviewing the above link!

@amontalenti
Copy link
Owner

amontalenti commented Sep 20, 2020

Also the GitHub Markdown rich visual diff here is handy for reviewing the consolidated changes across our commits:

https://github.com/amontalenti/elements-of-python-style/pull/50/files?short_path=04c6e90#diff-04c6e90faac2675aa89e2176d2eec7d8

Then click this icon for the rich diff:

rich-diff

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants