2nd hardest thing in computer science

@pawel_lewtak

Definition?

"There are only two hard things in Computer Science: cache invalidation and naming things."

Phil Karlton

Source: https://martinfowler.com/bliki/TwoHardThings.html

"There are 2 hard problems in computer science: cache invalidation, naming things, and off-by-1 errors"

Leon Bambrick

Source: https://twitter.com/secretgeek/status/7269997868

#2 Naming things*

*things

• variables
• methods
• classes
• modules
• comments
• inline docs
• commit messages

You don't code for CPU

You don't code for interpreter

You don't code for compiler

You code for people

You code for other developers

You code for your future self

Don't code,

wrote prose

Source: https://www.youtube.com/watch?v=CKONKZLmMwk

Source: https://trustartist.com/2015/01/27/pair-programming-economics/

"Writing software as if we are the only person that ever has to comprehend it is one of the biggest mistakes and false assumptions that can be made."

Karolina Szczur

Source: https://blog.andyet.com/2015/01/21/on-maintainable-front-end-systems/​

"Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do."

Donald E. Knuth

Source: Literate Programming , 1983

Comprehension

~70%

def a(b):
    c = sorted(b)
    d = len(b)
    if d % 2 == 1:
        return c[(d - 1) / 2]
    else:
        return (c[d/2 - 1] + c[d/2]) / 2

def median(pool):
    copy = sorted(pool)
    size = len(copy)
    if size % 2 == 1:
        return copy[(size - 1) / 2]
    else:
        return (copy[size/2 - 1] + copy[size/2]) / 2

Self-documenting code

Code written by somebody else

Programming is mapping

• from problem domain
• via intermediate domain
• into programming domain

DDD FTW

Worst variable name

data

Source: http://archive.oreilly.com/pub/post/the_worlds_two_worst_variable.html

Second worst name?

data2

total = price * qty
total2 = total - discount
total2 += total * taxrate

total3 = purchase_order_value + available_credit
if total2 < total3:
  print ("You can't afford this order.")

order_total = price * qty
payable_total = order_total - discount
payable_total += payable_total * taxrate

available_funds = purchase_order_value + availble_credit
if payable_total < available_funds:
  print ("You can't afford this order.")

"No-one sets out to write legacy code"

Rachel Willmer

Source: https://twitter.com/amokleben/status/868377283496751104?s=09

Broken window theory

Code will decay

Design patterns

Misapplied Java design ​patterns

are the root of all AbstractWordFactoryFactory("evil")

HN comment

Source: https://twitter.com/tmmx/status/865308678903267328

Naming conventions

TL;DR

• CamelCaseClass
• methodName
• someVariable
• CAPITAL_CONSTANT

syntax < semanthics

Pseudo getter

get_data()

with extra operations inside

get_create_object()

• fetch
• find
• lookup
• create
• calculate

Not really a boolean

is_active()

def is_active():
  if cond:
    return 'false'
  return 'true'

is_valid()

def is_valid():
  if input_is_valid:
    return True

Plural / singular names

def get_person():
  return ['John Doe', 'Jane Doe']

def get_employers():
  return 'John Doe'

Misleading docs

def get_lowest_price(user):
  pass

def get_lowest_price(user):
  """Actually it returns the highest price."""
  pass

<ThatThing>Manager

• UserManager
• StringManager
• ProductManager
• etc.

Alternatives

• Builder
• Writer
• Adapter
• Factory
• Handler
• Provider
• Converter

Magic numbers

import requests

response = requests.get('https://www.google.com/')
if response.status_code == 200:
  print ("It works!")
elif response.status_code == 418:
  print ("Unexpected teapot!")

import requests

response = requests.get('https://pl.pycon.org/')
if response.status_code == requests.codes.ok:
  print ("It works!")
elif response.status_code == requests.codes.teapot:
  print ("Unexpected teapot!")

Useless comments

def get_data():
  """ Returns the data. """
  pass

def get_max_id_from_db():
  """ Return maximum ID value from the database."""
  pass

Explain why,

not what or how

"Code should have comments, but if your file is more than 25% comments, that's a red flag: you may be explaining bad code"

Adam Culp

Commit messages

Do not use negation

is_not_enabled()

is_disabled()

Consistent names

Code & docs

Commit message

Good commit message

• Speeds up review process

• Helps write release notes

• Helps future maintainers

Short (50 chars or less) summary of changes

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Further paragraphs come after blank lines.

  - Bullet points are okay, too

  - Typically a hyphen or asterisk is used for the bullet, preceded by a
    single space, with blank lines in between, but conventions vary here

Source: Source: http://git-scm.com/book/ch5-2.html

How?

Agree on standards

Boy Scout Rule

Practice

Improve vocabulary

Refactor

Code reviews

Short, bite size, single logical change

Code ownership

Commit messages

Research papers

• https://www.cqse.eu/publications/2005-concise-and-consistent-naming.pdf
• http://www.cs.loyola.edu/~lawrie/papers/lawrieJese07.pdf
• https://www.researchgate.net/publication/224079441_Relating_Identifier_Naming_Flaws_and_Code_Quality_An_Empirical_Study
• http://www.veneraarnaoudova.com/wp-content/uploads/2014/10/2014-EMSE-Arnaodova-et-al-Perception-LAs.pdf​

Thank you!

@pawel_lewtak

Questions?

@pawel_lewtak