jldbc / jldbc/pybaseball

Developing a style guide

Open
#100 15 comments 0 reactions 0 assignees View on GitHub
feedback wanted governance question
Dominant language
Python
Stars
1.7k
Forks
428
PR merge metrics
No merged PRs in 30d

Description

So in a recent PR I tried to bring in some formatting changes (not necessarily on purpose, mostly because it was my first PR, and I always have some sort of auto pep 8 formatter on, 😆).

This led to quite a few unrelated code changes and some understandable concern on @schorrm 's part (expecially for some of the choices that were made by the formatter.

However, I think (and I believe @schorrm agrees to some extent) that adding some code style standards could be fruitful, and if we can all coalesce around a shared tool and config to keep it painless, the better! The goal of the style guide would to make the code more readable and internally consistent.

So I'd like to use this issue to discuss what some participants like in a style guide, don't like in a style guide, or are apathetic to.

I'll begin with a few of mine.
- I prefer capping lines at a length of 120, but am not opposed (and frequently will) break apart lines smaller than that if I feel like it will improve readability. For example:
```python
# Technically legal
cols = [col.replace('*', '').replace('#', '') for col in cols]

# More readable in my opinion
cols = [
col.replace('*', '').replace('#', '') for col in cols
]

# For extra long lines I'd even break it this way as well
cols = [
col.replace('*', '').replace('#', '').extraLongFunctionGoesHereToTakeUpRoom()
for col in cols
]
```

- Along those same lines I prefer to break apart long strings like this:
```python
my_string = "Pretend this string goes on for something like 120 characters... " +
"The rest of the string goes here."
```

- Along those same lines I think for long lines that are function calls, treating the function parens like curly brackets in other languages makes for a clean look:
```python
ata = fangraphs.get_fangraphs_tabular_data_from_url(
_FG_TEAM_PITCHING_URL.format(
start_season=start_season,
end_season=end_season,
league=league,
ind=ind,
)
)
```

- I prefer spacing around my type declarations, variable assignments, and operators:
```python
def team_pitching(start_season: int = None):
for season in range(start_season, start_season + 1):
pass
```

- For longer function definitions I prefer splitting them apart per parameter:
```python
def team_pitching(
start_season: int,
end_season: int = None,
league: str = 'all',
ind: int = 1,
):
```

- I also really prefer when the code gets a pylint score of 10.0, but there are some linting failures I don't flip out about (like docstrings on modules).

- When possible, I prefer type hinting in function params and returns so MyPy can help catch misuse before runtime.

- I would like to eliminate all print statements if possible. Print statements are an uncontrolled side effect for anyone using the library downstream. Instead we should use the logging library and give the user some control over where the logs go:

https://docs.python.org/3/howto/logging.html#logging-basic-tutorial

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.