"Any fool can write code that a computer can
understand. Good programmers write code that
humans can understand."
Martin Fowler
Slide 8
Slide 8 text
"Indeed, the ratio of time spent reading versus
writing is well over 10 to 1. We are constantly reading
old code as part of the effort to write new code. ...
[Therefore,] making it easy to read makes it easier to
write."
Uncle Bob (Robert C Martin)
Slide 9
Slide 9 text
Give your code a voice
Slide 10
Slide 10 text
1. Avoid meaningless words
2. Strive for consistency
3. Don't make my brain hurt
4. Name according to scope
5. Don't make me look things up
6. Leverage metaphors
Slide 11
Slide 11 text
1. Avoid meaningless words
Words that put my brain to sleep !
1. Avoid meaningless words
2. Strive for consistency
Slide 30
Slide 30 text
Pick a word and stick with it
echo $blog->body;
echo $comment->text;
echo $testimonial->content;
(2. Strive for consistency)
Slide 31
Slide 31 text
Pick a word and stick with it
echo $blog->body;
echo $comment->body;
echo $testimonial->body;
(2. Strive for consistency)
Slide 32
Slide 32 text
Pick a word and stick with it
$post->image;
$user->photo;
$tag->thumbnail;
(2. Strive for consistency)
Slide 33
Slide 33 text
Pick a word and stick with it
$post->image;
$user->image;
$tag->image;
(2. Strive for consistency)
Slide 34
Slide 34 text
Pick a word and stick with it
service.api_key
service.key
service.public_key
service.secret_key
service.api_secret
service.api_public
service.secret
...
(2. Strive for consistency)
Slide 35
Slide 35 text
Pick a word and stick with it
service.api_key
service.api_secret
(2. Strive for consistency)
Slide 36
Slide 36 text
1. Avoid meaningless words
2. Strive for consistency
3. Don't make my brain hurt
Slide 37
Slide 37 text
Abbreviations I'm ok with !
auth authentication // TODO
admin administrator
id identifier
db database
i iteration
int, bool integer / boolean
e, z exception / zonda
(3. Don't make my brain hurt)
Slide 38
Slide 38 text
Abbreviations I'm NOT ok with !
addr address
attr attribute
err error
arr array
opt option
msg message
img image
(3. Don't make my brain hurt)
Slide 39
Slide 39 text
Dates
date('j') / date('t') * 100;
(3. Don't make my brain hurt)
Slide 40
Slide 40 text
Dates
$dayOfMonth = date('j');
$totalDaysInMonth = date('t');
$dayOfMonth / $totalDaysInMonth * 100;
(3. Don't make my brain hurt)
Slide 41
Slide 41 text
Dates
(new DateTime)->setDate(date('Y'), date('m'), 1)->setTime(12, 0, 0);
(3. Don't make my brain hurt)
Slide 42
Slide 42 text
Dates
new DateTime('first day of this month midnight');
(3. Don't make my brain hurt)
Slide 43
Slide 43 text
Ugh! Regex
preg_replace('/\s\s+/', ' ', $title);
(3. Don't make my brain hurt)
Slide 44
Slide 44 text
Ugh! Regex
stripOutExtraWhitespace($title);
(3. Don't make my brain hurt)
Slide 45
Slide 45 text
Negatives !
if (! $post->isExpired()) {
(3. Don't make my brain hurt)
Slide 46
Slide 46 text
Negatives !
if ($post->isActive()) {
(3. Don't make my brain hurt)
Slide 47
Slide 47 text
Double Negatives ! !
$users->filter(function ($user) {
return $user->group !== 'admin';
});
(3. Don't make my brain hurt)
Slide 48
Slide 48 text
Double Negatives ! !
$users->reject(function ($user) {
return $user->group === 'admin';
});
(3. Don't make my brain hurt)
Slide 49
Slide 49 text
No content
Slide 50
Slide 50 text
1. Avoid meaningless words
2. Strive for consistency
3. Don't make my brain hurt
4. Name according to scope
Slide 51
Slide 51 text
Compound method names
class Cart {
public function addProduct() {};
public function removeProduct() {};
public function changeProduct() {};
}
$cart->addProduct();
(4. Name according to scope)
Slide 52
Slide 52 text
Compound method names
class Cart {
public products;
}
class Products {
public function add() {};
public function remove() {};
public function change() {};
}
$cart->products->add($product);
(4. Name according to scope)
Slide 53
Slide 53 text
!
Your names may be telling you that your code is
ready for a refactoring
Slide 54
Slide 54 text
Compound variable names
$transactionId;
$transactionDate;
$transactionAmount;
(4. Name according to scope)
Slide 55
Slide 55 text
Compound variable names
$transaction->id;
$transaction->date;
$transaction->amount;
(4. Name according to scope)
Slide 56
Slide 56 text
1. Avoid meaningless words
2. Strive for consistency
3. Don't make my brain hurt
4. Name according to scope
5. Don't make me look things up
Slide 57
Slide 57 text
Bare parameters
new Color(0, 12, 66);
(5. Don't make me look things up)
Slide 58
Slide 58 text
Bare parameters
Color::fromRGB(255, 255, 255);
Color::fromHSL(0, 0, 100);
(5. Don't make me look things up)
Slide 59
Slide 59 text
Bare parameters
new HttpRequest(500);
(5. Don't make me look things up)
Slide 60
Slide 60 text
Bare parameters
new HttpRequest($timeoutInSeconds = 500);
(5. Don't make me look things up)
Slide 61
Slide 61 text
Boolean flags
json_decode($json, true);
(5. Don't make me look things up)
Slide 62
Slide 62 text
Boolean flags
json_decode($json, $returnArray = true);
(5. Don't make me look things up)
Slide 63
Slide 63 text
Array Indexes
$user = DB::fetchRowArray(...
echo $user[2];
(5. Don't make me look things up)
Slide 64
Slide 64 text
Array Indexes
$user = DB::fetchRowAssociativeArray(...
echo $user['email'];
(5. Don't make me look things up)
Slide 65
Slide 65 text
Bare integer
$response = $request->post('/users', $payload);
$this->assertEquals(201, $response->statusCode());
(5. Don't make me look things up)
Slide 66
Slide 66 text
Bare integer
class HttpStatus {
const CREATED = 201;
}
$response = $request->post('/users', $payload);
$this->assertEquals(HttpStatus::CREATED, $response->statusCode());
(5. Don't make me look things up)
Slide 67
Slide 67 text
Implicit method name
$post->publish(); // queues internally
(5. Don't make me look things up)
Slide 68
Slide 68 text
Implicit method name
$post->queueAndPublish();
(5. Don't make me look things up)
Slide 69
Slide 69 text
Implicit method name
Post::getFirst(); // creates a new post if can't find one
(5. Don't make me look things up)
Slide 70
Slide 70 text
Implicit method name
Post::getFirstOrCreate();
(5. Don't make me look things up)
Slide 71
Slide 71 text
1. Avoid meaningless words
2. Strive for consistency
3. Don't make my brain hurt
4. Name according to scope
5. Don't make me look things up
6. Leverage metaphors
Slide 72
Slide 72 text
No content
Slide 73
Slide 73 text
"This transfer of some quality of the known to the
unknown is like a beam of light; we "see" (that is, we
understand) something about the unknown in the
light of the known."
Mary Oliver (A Poetry Handbook)
Slide 74
Slide 74 text
Common pattern in apps
$admin->logInAsOtherUser($user);
(6. Leverage metaphors)
Slide 75
Slide 75 text
Common pattern in apps
$admin->impersonate($user);
(6. Leverage metaphors)
Slide 76
Slide 76 text
Common pattern in APIs
$client->get('/users/currently_logged_in_user');
(6. Leverage metaphors)
Slide 77
Slide 77 text
Common pattern in APIs
$client->get('/users/me');
(6. Leverage metaphors)
Slide 78
Slide 78 text
Wrapping it up
Slide 79
Slide 79 text
1. Avoid meaningless words
2. Strive for consistency
3. Don't make my brain hurt
4. Name according to scope
5. Don't make me look things up
6. Leverage metaphors