Skip to content

Commit ab89b73

Browse files
committed
Added short style guide. Updated readme.
1 parent a5a0b12 commit ab89b73

3 files changed

Lines changed: 69 additions & 0 deletions

File tree

PythonStyleGuide.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
Notes about coding style
2+
-----------------------
3+
4+
As noted by one of your colleagues after the tutorial, good coding style is
5+
fundamental. It is specially important when someone has to mark your code. To
6+
help yourself write pretty Python code, your anonymous style-hero classmate and
7+
I recommend the package `flake8`, that you can easily pip inside your virtual
8+
environment:
9+
10+
```
11+
pip install flake8
12+
```
13+
14+
Now you can run the command `flake8` on any Python script and it will tell you
15+
where and why it looks ugly, according the the world-famous **PEP8 Style
16+
Guide**. PEP8 is a standard of good coding practice and should be respected,
17+
particularly in collaborative projects.
18+
19+
That said, I politely disagree with some of the conventions in PEP8, and I have
20+
deliberately chosen to not follow them in the exercise scripts. These are the
21+
specific PEP8 sections I respectfully ignore:
22+
23+
*Disclaimer*: all the lines below start with "I" because it's all my personal
24+
preference. But those are like opinions --- everybody has one. You don't have
25+
to stare at mine for any longer than you deem appropriate.
26+
27+
1. I prefer indentations with 2 spaces rather than 4.
28+
29+
2. I think it's a good idea to leave an empty line at the end of a script.
30+
31+
3. I'm ok with leaving extra spaces at the sides of operators to align several
32+
statements.
33+
34+
4. I tend to begin code "sections" with double-hashed comments, i.e. coments
35+
starting with '## '. This disagrees with the PEP8 mantra that forces all
36+
comments to start with '# '.
37+
38+
To stop flake8 from complaining all the time about these, I style-check my
39+
python scripts with the following command:
40+
41+
flake8 myFancyScript.py | grep -Ev 'E221|E111|E265|W391'
42+
43+
**Some marks of the assessed coursework are reserved for style and clarity**.
44+
We won't strictly enforce all PEP8 guidelines, but it's probably a good idea
45+
to try to follow it.
46+
47+
Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Selected student comments after the Python tutorial
2+
---------------------------------------------------
3+
4+
Thanks to everyone who came along and for the helpful feedback. I've taken the
5+
priviledge of correcting some typos in your messages. Here are some of the
6+
tutorial Python-esque afterthoughts:
7+
8+
- It's a snake?
9+
10+
- Maybe you can also suggest students to go to
11+
https://www.codecademy.com/en/tracks/python where the Python course is a very
12+
good learning resource.
13+
14+
- Please use a common coding style (I suggest flake8). It makes the code easier
15+
to read and it teaches the beginners good coding from the beginning.
16+
17+
- Why not pie thon?
18+
19+
- Ssssssss
20+

README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@ notifications.
2929

3030
## News
3131

32+
- 26.X.2015: Added Python style guide.
33+
- 26.X.2015: Added Ex1 solutions and the rest of Ex2.
3234
- 22.X.2015: Added slides for the Python tutorial. Added some code for Ex2.
3335
- 19.X.2015: Replaced .docx files with .pdf files to make equations readable.
3436
- 18.X.2015: Added code and problem sheet for Exercise 1.

0 commit comments

Comments
 (0)