Beyond the Style Guides

Beyond  
the Style Guides
Mosky

It's all about time.
I can write a 4x faster program than you!
But the hardware is super powerful now, 
it may be just 0.0001 ms vs. 0.0004 ms.
I can write 4x faster.
And human brain haven't changed a lot, 
so it may be even 1 week vs. 1 month.
Human Time ⋙ Computer Time

- Benjamin Franklin
“Time is money.”

How to write faster?
Good language, e.g., Python
Powerful libraries
Experience
∈ The things you can't change immediately.

Understandable codebase. 
i.e., codebase which has high maintainability.
∈ You can just learn from this share.

Style Guide?
# It looks okay! 
count += 1

Not enough
# But it was initialized as 
count = '1'
# In JavaScript,  
# there's even no an error.

You remain only 10k days in your life.

Spend time on writing exciting feature, 
not debugging.

Mosky
Python Charmer at Pinkoi
The author of the Python packages
MoSQL, Clime, …
The speaker of the conferences,
PyCon TW/JP/SG, …
Also teaching Python
mosky.tw

A Computer
Read the code line by line.
Cover all of the code, usually.
Just complain when it doesn't understand.

A Human Brain
We can't read code like a computer.
CPU is super slow, and even can't focus.
RAM is tiny, programmer especially.
Disk is losing bytes all the time.
Nobody to complain.
So we prefer to leave code alone.

But, computer is always complaining.
We jump to the failed line.
Read back from the line.
Finally,  
we leave immediately after we ﬁx it.

Or, new requirement comes.
We still jump to the related line.
Read back from the line.
Finally,  
we also leave immediately after we ﬁnish it.

Maintainability
To understand a random line,  
how many lines do you need to read back?
Lesser → Higher maintainability

Nothing But
Have a good dictionary.
Be exact to avoid ambiguity.
Be consistent to avoid misleading.
Hint, hint, and hint.

Be Exact
“Apple”
Which “Apple”?
“Apple, the company.”
apple_the_company

date_a-date_b
Which dates?
today-joined_date

user
User’s what?
user_name
user_email

name
Who’s name?
user_name
store_name

Be Consistent
Saw this in somewhere:
apple = Company('apple')
Now you read:
apple
Then you will guess it is a company. So don't:
apple = Fruit('apple')

Too Long?
The context helps.
fruit.py
apple

Type Hint
We operate variables.
count += 1
parse(input_json)
If we know how to operate it at ﬁrst glance, 
it saves time from tracing or running.
Not the “Type Hint” in PEP 0484

Make It Intuitive
count
should be numeric
name
string thing
names
many strings; may be a list

page
page_no
so should be numeric
event
event_key
so should be string stuff

List or Set?
requested_fields & allowed_fields
?
set(requested_fileds) & allowed_field_set

List or Generator?
large_rows
large_rows[0] # ?
large_row_gen # generator
large_row_it # iterator

Object or Dict?
user
What is the type of user?
user['name'] # ?
user.name # ?
user_dict['name']
user_d['name']

Is it a bool?
new_user
A bool? A User instance?
is_new_user
A bool? A Function?
new
user_is_new

Is it a function?
Use imperative, i.e., start with a verb.

.text
.json
A function? A string thing?
.get_text
.parse_from_json
.text # string thing

def parse(x, return_dict=False): …
?
def parse(x, to_return_dict=False): …

Explicit Unknown
arg
May be tuple, dict, or anything.
arg_x

Avoid None
d = None if failed else {} 
d['key'] = value 
value = d.get('key')
It causes TypeError or AttributeError in Python,
and extra effort in other language.
Be consistent in type.

Some tips
Raise exception.
Use zero and inﬁnite.
Use constant.
Filter the Nones out before return.

Content Type
User Input
The “Keys”
URL
JSON
HTML
SQL
∈ string thing

json['keyword'] # ?
Actually the json is a dict-like.
JSON: JavaScript Object Notation → a string
arg_dict = json.loads(arg_json)
Transformation
You can see the domain and codomain.

template.format(name)
If
template # -> "<a>{}</a>"
name # -> "<script src=…></script>"
!

template_html.format(escape(name))
Safe :)
“Making Wrong Code Look Wrong “

Abstract Type
it — iterator
seq — sequence
map — mapping

Structure Hint
We operate the variables.
(Yeah, I copied it from the type hint.)

Map
users
A dict? What are the key and the value?

uid_user_map 
uid_user_map['mosky'] # -> User('mosky')

# ok 
users = { 
'mosky': User('mosky'), 
… 
}
# even better 
uid_user_map = { 
'mosky': User('mosky'), 
… 
}

Tuple
uid, name = uid_name_pair
a, b, c = a_b_c_tuple

key_value_pairs = sql('select key, value')
for key, value in key_value_pairs: 
…
key_value_map = dict(key_value_pairs)

Composite
If apply structure hint and type hint,
It will be long.
You may shorten.
Keep long description in comment or doc.

Use common abbreviation
http://abbreviations.com/
Use acronym, e.g., rlname for really_long_name.
Do comment if you use them.

# compromise between meaning and length 
# 
# event key: e.g., 'monthers_day' 
# config_d: config dict 
# 
# - start_date: … 
# … 
# 
event_key_config_d_map = { 
'monthers_day': {…} 
}

# focus on reducing length 
# 
# ekey: event key 
# config: config dict 
# 
# - start_date: … 
# … 
# 
ekey_config_map = { 
'monthers_day': {…} 
}

adj. new_user
past participle joined_date
present participle working_queue
inﬁnitive keys_to_remove
another noun template_args

int
n, m 
i, j, k 
twd_int
int/range
page_no 
birth_month 
birth_day
tids_idx
bool
new, joined 
user_is_new 
new_or_not 
new_bool

str name, month_str
str/key event_key
str/url next_url
str / json user_json
str/html page_html
str/sql to_update_sql

dict user_d, user_dict
list uids, uid_list
set uid_set
mapping uid_user_map
generator uid_gen

date start_date
datetime joined_dt
re email_re
decimal total_dec
currency
total_currency, total_ccy 
total_twd

key → value uid_user_d_map
(x, y) uid_user_pair
[(x, y), …] uid_user_pairs
(x, y, z) uid_nick_email_tuple

Return Type Hint
We operate the variables.
(Yeah, I copied it from type hint, again.)

.parse
What we will get?
.parse_to_tree

.allow_to_log_in
Allow something to log in?
.do_allow_to_log_in
If return value is a bool, use yes–no question.

Performance Hint
get_name # Memory op.
parse_from_json # CPU op.
query_html 
request_html # IO op.
Let reader know the roughy cost.

Private Hint
“Don't touch me hint”
A simple underscore preﬁx (_)
Don't use me out of the module or ﬁle.
Non-privates are just public APIs.

Hints
Type Hint
Structure Hint
Return Type Hint
Performance Hint
Private Hint

A random line now is more understandable.

Blank Line
Use blank line to separate your code into:
Paragraph
Section
Like lightweight markup language, 
e.g., Markdown, RST.

Paragraph
Lines without any blank line.
Group similar lines into a paragraph.
Contains sub-paragraph.
Use blank line to separate paragraphs.

try: 
html = read_html_from_cache(url) 
except IOError: 
html = request_html(url)

Section
Paragraphs.
Group similar paragraphs into a section.
Avoid sub-section.
Use two blank lines to separate sections.

<section A's paragraph 1> 
 
<section A's paragraph 2> 
 
 
<section B's paragraph 1> 
 
…

Still don't understand? 
Try to read a paragraph, then a section.

Dependency
The F function calls the G function.
F depends on G.
F → G
It's a “Line”.

How messy?
Are the directions are all same?
Usually ↑ in a file and files.
Order your code.
Are they point to limited sections or a files?
Lesser is better.
Section or modularize them.

Reality
Don't have time to refactor.
They actually work well.
Make you itch, but won't beat you.
You may already understand.

So Just Seal It Off
Comment the pitfalls.
Use #TODO rather than really refactor.
Assign return value to a better named variable.
Wrap them.
Just write new code.

Recap
We read lines randomly.
Type hints and other hints
Paragraph & section by blank line.
Line your functions.
Bad smell won't beat you.
http://mosky.tw

Beyond the Style Guides

More Related Content

What's hot (20)

Viewers also liked (19)

Similar to Beyond the Style Guides (20)

More from Mosky Liu (7)

Recently uploaded (20)

Beyond the Style Guides