Writing code that works and writing code that other people can read and understand are two different skills. And writing code that other people can read and understand became more and more essential skills as the project grows larger, and more people start working on it. But because it is a skill, you need to train it consciously. It's a lot like writing essays and books. Everybody can write letters and words; many can also connect them in grammatically correct sentences. But not everybody is a J. R. R. R. Tolkien and have their books read by everyone. An essential part of learning this skill is reading and analyzing other people's code on the one hand. And making other people read your code and give you feedback about it. The speaker will talk about different methods of how to make programmers better writers and how to work out the skill of writing code that other people will want to read.

1. Writing code for people
Alexey Ivanov, Evil Martians

3. Evil Martians

4. Evil Martians

6. Let's talk about
writing

7. — Know how to write letters?
— Know how to write words?
— Know how to write sentences?
— Do you write emails, Line messages, or tweets every day?
— Published articles in magazines or books?
Do you know how to write?
7

8. Writing code is the
same

9. — You open your code from one year ago and can't remember how it works.
— You spend half of the day adding debug and console.log to functions
to see what they are doing.
— You tried to read another person's code and can't understand it.
— ^ Another person probably thought the same about your code too.
Have you been in these situations?
9

10. Most of programming tutorials and books teach how to write code that can
be understood by the computer and do some stuff with it.
Very few books and tutorials teach how to write code that other people can
read and understand.
This is a common situation
10

11. You write code once. But you and other people will be reading and modifying
it tens or even hundreds of times after that.
So it's crucial to write code that is readable, reusable, and refactorable.
But it's not a good situation
11

13. Writing code for
people

14. As with any other skill, if you will be mindful of what you are writing and spend
enough time training, you will become better at this.
It's a skill that can be learned
14

15. 1. Writing the code — principles, rules, style guides, and linters.
2. Reading the code — how to train yourself to become a better writer.
Talk structure
15

16. Writing the code

17. 1. Clean code.
2. Easy to understand code.
3. Code that shares context.
Writing the code
17

18. Clean code

19. — Select one code style.
— Automate it.
— Forget about it.
Clean code
19

20. There are tons of existing style guides:
— https://standardjs.com/
— https://github.com/airbnb/javascript
— https://google.github.io/styleguide/jsguide.html
— Standard Prettier settings
Choose any of them. It's not important which one. Don't spend time on that.
Select a code style
CLEAN CODE
20

21. — eslint for Javascript or TypeScript.
— stylelint for CSS.
— rubocop for Ruby.
— prettier — tool that can automatically fix style for multiple languages.
Linters usually have excellent documentation about when and why to use
each rule.
Add linters
CLEAN CODE
21

22. — eslint-config-airbnb
— eslint-config-standard
— stylelint-config-standard
The good thing about using a popular style guide is the fact that it is already
automated.
Add standard config for linters
CLEAN CODE
22

23. — Add prettier and linter plugins to your editor.
— Enable automatic fixing in prettier .
— Add precommit hook that automatically format/lint your code.
— Run your checks in CI (CircleCI or TravisCI will do).
Enable automatic linting and fixing
CLEAN CODE
23

24. Demo

25. Again, it's not important what style you choose. Toss a coin if you like. You
can always automatically reformat it later.
Forget about it
CLEAN CODE
25

26. Easy to
understand code

27. 1. Readability.
2. Complexity.
3. Reading flow.
Easy to understand code
27

28. Bad:
const yyyymmdstr = moment().format("YYYY/MM/DD");
Good:
const currentDate = moment().format("YYYY/MM/DD");
Use meaningful and pronounceable
variable names
READABILITY
28

29. Bad:
setTimeout(blastOff, 86400000);
Good:
const MILLISECONDS_IN_A_DAY = 86_400_000;
setTimeout(blastOff, MILLISECONDS_IN_A_DAY);
Use searchable names
READABILITY
29

30. Bad:
function createMenu(title, body, buttonText, cancellable) {
// ...
}
createMenu("Foo", "Bar", "Baz", true);
Function arguments (2 or fewer ideally)
READABILITY
30

31. Good:
function createMenu({ title, body, buttonText, cancellable })
// ...
}
createMenu({
title: "Foo", body: "Bar",
buttonText: "Baz", cancellable: true
});
Function arguments (2 or fewer ideally)
READABILITY
31

32. Bad:
function createFile(name, temp) {
if (temp) {
fs.create(`./temp/${name}`);
} else {
fs.create(name);
}
}
Don't use flags as function parameters
READABILITY
32

33. Good:
function createFile(name) {
fs.create(name);
}
function createTempFile(name) {
createFile(`./temp/${name}`);
}
Don't use flags as function parameters
READABILITY
33

34. — Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin
⽇本語
— https://github.com/ryanmcdermott/clean-code-javascript ⽇本語 —
examples was from there.
— https://github.com/ryanmcdermott/3rs-of-software-architecture
— JS UX: Writing code for Humans by Lea Verou
Further reading
READABILITY
34

35. One of the sighs of the bad code is complexity:
— Large functions that do multiple things at once.
— Too many arguments for the function.
— Multiple nested IFs or callbacks.
Complexity
35

36. You can automate detection of such things. For example with Eslint:
— complexity — Cyclomatic Complexity
— max-depth
— max-statements
— max-nested-callbacks
Be careful. Following these rules blindly can produce harder to read code.
Automation
COMPLEXITY
36

37. — How often do you go back and forth between functions and methods in the
file?
— How many files do you need to open to understand how something works?
— Are the files that you are switching between are close to each other or do you
need to go to different nested folders?
Sometimes it is better to break complexity rules to make the reading
flow easier.
Reading flow
37

38. dropdown/
locale/
en.json
jp.json
index.js
index.test.js
readme.md
styles.css
Place things close to each other
READING FLOW
38

39. Code that shares
context

40. Old code:
window.ga("send", {
hitType: "event",
eventCategory: "Videos",
eventAction: "play",
eventLabel: "Fall Campaign",
eventValue: 10
});
Replacing GA with GTM
EXAMPLE
40

41. New code:
window.dataLayer.push({
category: "Videos",
action: "play",
label: "Fall Campaign",
value: 10
});
Replacing GA with GTM
EXAMPLE
41

42. Solution:
const event = { /* ... */ }
const eventPlaceholder = {
label: undefined, value: underfined
};
window.dataLayer.push({ ...eventPlaceholder, ...event });
Replacing GA with GTM
EXAMPLE
42

43. 1. You can't just leave the code" as is" – next developer can delete it while
refactoring, and they spend eight more hours debugging it.
2. You can't ask other people to review this code without telling them what it is
doing and why.
3. Other people can't update and maintain this code.
But how do you share this knowledge?
43

44. /*
GTM sets all event fields as global variables inside itself,
so until we rewrite them, they will have old values. Because
label and value are optional fields, we need to unset them
for the next events explicitly. Relevant docs:
- https://developers.google.com/tag-manager/devguide
- https://support.google.com/tagmanager/answer/6164391?hl=en
*/
Use comments
44

45. Code can't explain why the program is being written, and the rationale for
choosing this or that method. Code cannot discuss the reasons certain
alternative approaches were taken.
Jeff Raskin
What is context?
“
45

46. For example:
/* A binary search turned out to be slower than the
Boyer-Moore algorithm for the data sets of interest,
thus we have used the more complex, but faster method
even though this problem does not at first seem
amenable to a string search technique. */
Jeff Raskin
What is context?
46

47. @media (--sm-scr) {
.input {
font-size: 16px; /* prevents iOS auto-scale on focus */
}
}
CSS example
47

48. React Source

49. GIT Source

50. — The reader needs a context that can't be expressed using other means.
— The code exists because of the environment issues. Browser bugs, for
example.
— The ugly solution is chosen because of speed optimization reasons.
When to comment
50

52. — Code Tells You How, Comments Tell You Why by Jeff Artwood
— The Art of Comments by Sarah Drasner
Links
52

53. 1. Clean code.
2. Easy to understand code.
1. Readability.
2. Complexity.
3. Reading flow.
3. Code that shares context.
Summary of the first part
53

54. Reading the code

55. 1. Code reading.
2. Code reviews.
3. Pair Programming.
Reading the code
55

56. Code reading

57. Douglas Crockford — Goto There and Back Again starting from 27:15
Code reading
57

58. Crockford's method:
1. Do it every day.
2. Discuss approaches, patterns, and possible solutions.
3. Don't judge. Don't use results as metrics.
Code reading
58

59. Who should read:
1. Reading by the author — faster to do, better at describing context, but
fewer chances to find problems.
2. Reading by the other person — slower, requires more steps, more useful
feedback on writing.
Code reading
59

60. You can use methodology from usability testings for the additional effect:
— Think aloud. Make assumptions about what variables and functions will do.
— Check if these assumptions were correct.
— See how much time you spend on each block.
— See how often you switch between files and sections inside the file.
Read more: Thinking Aloud: The #1 Usability Tool
Code reading
60

61. Read the code from open-source projects that you use together in the same
way:
— You will have a better understanding of how they work.
— You will see which approaches to writing code works and which don't.
Code reading
61

62. — https://github.com/reduxjs/redux
— https://github.com/mobxjs/mobx
— webpack loaders
Some projects to start from
62

63. Code review

64. Principles of the clean code apply to commits and PRs as well:
— Short, <200LOC PRs.
— Do only one thing.
— Describe the context.
Code review
64

65. If you have large PR — split them to the smaller parts:
1. Refactoring filenames? Create PR.
2. Changing the React component that is used in multiple places? Create PR.
3. Making new utility for everyone to use? Create PR.
Split to many small PRs
CODE REVIEW
65

66. You can (and should) use commit messages and PR description to describe
the task's context:
1. What was the task?
2. Why did you choose to solve it in this way and not another?
Describe context
CODE REVIEW
66

67. Things that should be done before code review:
— Discuss the PR process and decide who and how fast should review them.
— Chose style guide and enable linters.
— Discuss the new APIs before starting writing code for them.
Advance preparation
CODE REVIEW
67

68. 1. Split large PRs that need to be merged all at once in the separate commits
that only do one thing.
2. Give each commit a meaningful name.
3. Before pushing to upstream, make your commit history beautiful: Squash,
rename, and clean up your commits.
Can't split to different PRs?
CODE REVIEW
68

70. Links:
— http://ohshitgit.com/
— https://chris.beams.io/posts/git-commit/
— https://sethrobertson.github.io/GitBestPractices/
Code review
70

71. Pair programing

72. How to use to become a better writer:
— Discuss the plan and make a basic structure.
— Split tasks so both sides can program and not only listen.
— Comment what you are trying to do now.
— Give real-time feedback and ask questions.
Pair programing
72

73. Writing:
1. Clean code.
2. Easy to understand code.
1. Readability.
2. Complexity.
3. Reading flow.
3. Code that shares context.
Reading:
1. Code reading.
2. Code reviews.
3. Pair Programming.
Summary of the talk
73

74. Alexey Ivanov, Evil Martians
Twitter: @iadramelk
Writing code for people
74