owned this note changed 5 years ago
Published Linked with GitHub
tags: WebHack#31

Write Code that All like to Read

Speaker: Ivanov Alexey
Slides: Writing code for people

Introduce "Evil Martians"

  • Software consultancy
  • Do open source projects
  • Many branches in the different countries

Let's talk about writing

  • Start with a simple question "Do you know how to writing?"
  • We write everyday, ex: email, messages and articles
  • We write code and read code which we wrote and others wrote, sometimes the code is hard to understand
  • Most tutorials teach you how to write code that computers can understand, but fewer tutorials teach you how to write code that people can undersand

Readable, reusable and refactorable

  • How to measure software quality
    Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →
  • It's a skill which can be trained and learned

Write the code

Clean code

  • select one code style
    • Choose any of them, It's not important which one. Just choose one of them
  • automate it
    • Add linters read the documents of linters to understand each rule
    • Add standard configs into linters
    • Enable automatic linting and fixing

Easy to understand code

  • Readability

    • Use meaningful names
    • Use searchable names
    • Fewer function arguments
    • Don't use flags as function parameters
    • (please refer to further reading)
  • Complexity

    • High complexity: Large functions, too many arguments or too many if conditions
    • Use tool to automatically detect this situation
  • Reading flow

    • How often do you go back and forth between methods?
    • How many files do you need to open to understand one features?
    • Place things close to each other
  • Code that shares context

    • Example (please refer to the slides)
    • How to you share this knowledge of complex implementation?
      • If the complex is necessary, "Use comments" to share the knowledge/reason
    • What is context?
      • The reason of this (unintuitive) implementation
    • When to comment
      • The reader needs a context that can't be expressed using other means
      • The code handle environment issues
    • Code Tells You How, Comments Tell You Why

Reading the code

Code reading

  • Goto there and back again
  • Crockford's methods
    • Do it every day
    • Discuss approaches, patterns, and possible solutions.
    • Don't judge. Don't use results as metrics
  • Who should read?
    • Reading by the author
    • Reading by the other people slower, requires more steps,
  • Methodology
    • Think aloud, and make assumption
    • 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 files
  • Read the code from open source project that you use
    • Have a better understanding
    • See which approaches to writing code works and not works

Code review

  • Principles of the clean code apply to commits and PRs as well
    • Short, < 200 LOC PRs
    • Do only one thing
  • Split to many small PR
  • Describe context
  • Advance preparation
    • Discuss the PR process and decide who and how fast should review them
    • Chose style guide and enable linters
    • Discuss the new APIs before implementing
  • Can't split to different PRs
    • Split large PRs into the separate commits with meaningful messages

Pair programming

  • How to use
    • Discuss the plan and make a basic structure
    • Split tasks
    • Comment what you try to do now

Q & A

Question: How to avoid PRs block development process?
Ans:
- Discuss with the reviewer what you want to do

Question: How much time you spend on PRs?

Question: How to measure the size of code while using different language?

Question: How to read code which wrote long time ago? And how to find the dead code?
Ans:
- Sometimes it's possible to use some tools to dectect

Question: How to handle the pull request depending on another pull request?
Ans:
- Basically, you have to handle the rebase branch by yourself.

Select a repo