###### tags: `WebHack#31`

# Write Code that All like to Read

Speaker: __Ivanov Alexey__
Slides: [Writing code for people](https://www.slideshare.net/iAdramelk/writing-code-for-people-228709457)

## 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 
- 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](https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/)

## Reading the code

### Code reading
- [Goto there and back again](https://youtu.be/rJ-CoeWc19o)
- 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.