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.

Sign up for GitHub

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

doc: add style guide #746

Merged
merged 6 commits into from
Jul 15, 2022
Merged

doc: add style guide #746

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e4e6ebb
doc: add style guide
black-sliver Jul 5, 2022
6b845f9
doc: style guide for python and markdown
black-sliver Jul 5, 2022
339d653
doc: consistent use of periods and explicit double quotes in style guide
black-sliver Jul 6, 2022
71865a5
doc: better define string style in style guide
black-sliver Jul 6, 2022
47b11aa
doc: add format string literals to style guide
black-sliver Jul 6, 2022
b326100
doc: add HTML, CSS and JS to style guide
black-sliver Jul 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions docs/style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Style Guide

## Generic

* This guide can be ignored for data files that are not to be viewed in an editor.
* 120 character per line for all source files.
* Avoid white space errors like trailing spaces.
Ijwu marked this conversation as resolved.
Show resolved Hide resolved


## Python Code

* We mostly follow [PEP8](https://peps.python.org/pep-0008/). Read below to see the differences.
* 120 characters per line. PyCharm does this automatically, other editors can be configured for it.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i hate limiting line lengths, its more importent to create good readable code. even if some parameters are not directly visable on screen. it can still be better readable then splitng a function call over multiple lines

Also 120 is a really old value people used when they resolutuions of max 1024px

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

120 will make two code windows fit side-by-side on modern screens. 80 was the old one.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I use a 120 character limit for all my projects, and it's the default in JetBrains products, which we recommend.

* Strings in core code will be `"strings"`. In other words: double quote your strings.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why enforce double quotes? if a string uses double or single quote, your editor will color it as string, doesnt matter which veriant you use

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To make the core code consistent. This was discussed in discord and the majority was for using "

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i do prefer double quotes but i hate making it a rule, single quotes have thier use, like if you want to escape a double quote
like 'Received Item:: "{item.name}"'

Copy link
Member Author

@black-sliver black-sliver Jul 14, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Python agrees with you on that one

>>> "\"test\""
'"test"'
>>> '\'test\''
"'test'"

I don't think we have specified what to do in that case, and I doubt a PR gets rejected for "\"" or '"'.

* Strings in worlds should use double quotes as well, but imported code may differ.
* Prefer [format string literals](https://peps.python.org/pep-0498/) over string concatenation,
use single quotes inside them: `f"Like {dct['key']}"`
* Use type annotation where possible.


## Markdown

* We almost follow [Google's styleguide](https://google.github.io/styleguide/docguide/style.html).
Read below for differences.
* For existing documents, try to follow its style or ask to completely reformat it.
* 120 characters per line.
* One space between bullet/number and text.
* No lazy numbering.
black-sliver marked this conversation as resolved.
Show resolved Hide resolved


## HTML

* Indent with 2 spaces for new code.
* kebab-case for ids and classes.


## CSS

* Indent with 2 spaces for new code.
* `{` on the same line as the selector.
* No space between selector and `{`.


## JS

* Indent with 2 spaces.
* Indent `case` inside `switch ` with 2 spaces.
* Use single quotes.
* Semicolons are required after every statement.
8 changes: 4 additions & 4 deletions docs/world api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -236,7 +236,7 @@ class MyGameLocation(Location):
game: str = "My Game"

# override constructor to automatically mark event locations as such
def __init__(self, player: int, name = '', code = None, parent = None):
def __init__(self, player: int, name = "", code = None, parent = None):
super(MyGameLocation, self).__init__(player, name, code, parent)
self.event = code is None
```
Expand Down Expand Up @@ -487,14 +487,14 @@ def create_items(self) -> None:
for item in map(self.create_item, mygame_items):
if item in exclude:
exclude.remove(item) # this is destructive. create unique list above
self.world.itempool.append(self.create_item('nothing'))
self.world.itempool.append(self.create_item("nothing"))
else:
self.world.itempool.append(item)

# itempool and number of locations should match up.
# If this is not the case we want to fill the itempool with junk.
junk = 0 # calculate this based on player settings
self.world.itempool += [self.create_item('nothing') for _ in range(junk)]
self.world.itempool += [self.create_item("nothing") for _ in range(junk)]
```

#### create_regions
Expand Down Expand Up @@ -628,7 +628,7 @@ class MyGameLogic(LogicMixin):
def _mygame_has_key(self, world: MultiWorld, player: int):
# Arguments above are free to choose
# it may make sense to use World as argument instead of MultiWorld
return self.has('key', player) # or whatever
return self.has("key", player) # or whatever
```
```python
# __init__.py
Expand Down