Writing code for people
1 like•603 views
The document discusses the importance of writing code that is readable and understandable by others, emphasizing that coding is akin to writing for people. It outlines principles of clean code, readability, and context-sharing, along with methods for improving code writing and reading practices, such as using style guides and linters. Additionally, it highlights the value of code reviews and pair programming as tools to enhance collaborative coding skills.
Writing code for people
- 1. Writing code for people Alexey Ivanov, Evil Martians
- 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
- 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
- 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
- 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
- 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
- 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