|
| 1 | +# Coding Best Practices |
| 2 | + |
| 3 | +<img src="https://imgs.xkcd.com/comics/standards_2x.png" width="400" alt="Coding practices meme from xkcd"> |
| 4 | + |
| 5 | +## Introduction |
| 6 | + |
| 7 | +Best practices are a set of guidelines that help you write code that is easy to read, understand, and maintain. They are a set of rules that you should follow when writing code. They are not rules that you must follow, but they are recommended. |
| 8 | + |
| 9 | +We follow the [WordPress Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/). For PHP, you can inspire from https://github.com/piotrplenik/clean-code-php |
| 10 | + |
| 11 | +But this is not enough... |
| 12 | + |
| 13 | +## Code for the Team |
| 14 | + |
| 15 | +> When you write code, you are not writing it for yourself. You are writing it for the team. You are writing it for the future you. You are writing it for the future team members. You are writing it for the future clients. -- Copilot, April 2023 |
| 16 | +
|
| 17 | +The sign of code quality are: |
| 18 | +- Easy to read and understand. |
| 19 | +- Easy to maintain. |
| 20 | +- Easy to extend. |
| 21 | +- Easy to debug. |
| 22 | + |
| 23 | +To general, let's make an example for it: |
| 24 | + |
| 25 | +Suppose you have this task: `Given a list of numbers, sum only the even numbers.` |
| 26 | + |
| 27 | +A simple book-like solution would be: |
| 28 | + |
| 29 | +```javascript |
| 30 | +const numbers = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]; |
| 31 | + |
| 32 | +let sum = 0; |
| 33 | + |
| 34 | +for ( let i = 0; i < numbers.length; i++ ) { |
| 35 | + if ( numbers[ i ] % 2 === 0 ) { |
| 36 | + sum += numbers[ i ]; |
| 37 | + } |
| 38 | +} |
| 39 | + |
| 40 | +console.log( sum ); |
| 41 | +``` |
| 42 | + |
| 43 | +This is a simple solution. But it can be better. Let's refactor it: |
| 44 | + |
| 45 | +```javascript |
| 46 | +const numbers = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]; |
| 47 | + |
| 48 | +const sum = numbers |
| 49 | + .filter( ( number ) => number % 2 === 0 ) |
| 50 | + .reduce( ( sum, number ) => sum + number, 0 ); |
| 51 | + |
| 52 | +console.log( sum ); |
| 53 | +``` |
| 54 | + |
| 55 | +Why is this better? |
| 56 | + |
| 57 | +- It is easier to read and understand. When you have a classic `for` loop, you need to read the whole loop to understand what it does. With the `filter` and `reduce` functions, you can understand what it does by reading only the first line. `filter` and `reduce` are specialized loops, they have a specific purpose. |
| 58 | +- Easy to maintain. It it easier to spot where to make a change. |
| 59 | +- Easy to extend. If the numbers are send as `string` instead of `number`, you can easily change the code to convert them to `number` before filtering and reducing. Example: Add `.map( ( number ) => parseInt( number, 10 ) )` before filter. |
| 60 | +- Easy to debug. The functionality is modular, so you can remove things one at the time and check them. One neat trick you can do is to create an inspection function like this: |
| 61 | + |
| 62 | +```javascript |
| 63 | +const inspect = ( value ) => { |
| 64 | + console.log( value ); |
| 65 | + return value; |
| 66 | +}; |
| 67 | +``` |
| 68 | + |
| 69 | +Then, you can add it in the chain like this: |
| 70 | + |
| 71 | +```javascript |
| 72 | +const sum = numbers |
| 73 | + .filter( ( number ) => number % 2 === 0 ) |
| 74 | + .map( inspect ) |
| 75 | + .reduce( ( sum, number ) => sum + number, 0 ); |
| 76 | +``` |
| 77 | + |
| 78 | +This will out the result at each step of the chain. This is very useful when you need to debug a chain of functions. |
| 79 | + |
| 80 | +The first version might me more faster, but if the code is running only at a press of a button or an event, it is not a big deal. |
| 81 | + |
| 82 | +## Elegant Code |
| 83 | + |
| 84 | +In era of generated code, we still need to have elegant code. At the end of the day, we are still writing code for humans (this might be obsolete in feature). We need to write code that is easy to read and understand. |
| 85 | + |
| 86 | +Since the beginning of coding, people made a lot of articles and principles about how to write elegant code. Here are some of them: |
| 87 | + |
| 88 | +- DRY (Don't Repeat Yourself) - [Wikipedia](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) |
| 89 | +- KISS (Keep It Simple, Stupid) - [Wikipedia](https://en.wikipedia.org/wiki/KISS_principle) |
| 90 | +- YAGNI (You Ain't Gonna Need It) - [Wikipedia](https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it) |
| 91 | +- SOLID - [Wikipedia](https://en.wikipedia.org/wiki/SOLID) |
| 92 | +- Design Patterns - [Wikipedia](https://en.wikipedia.org/wiki/Software_design_pattern) |
| 93 | + |
| 94 | +## Performance |
| 95 | + |
| 96 | +If you come from a background where performance is a big deal, you might be tempted to write code that is optimized for performance. Example: game development, HPC, etc. |
| 97 | + |
| 98 | +In this project, we do not have cases when the code must do a lot of things at a high rate (like rendering a scene in a game). So, we can write code that is easy to read and understand, and we can optimize it later if needed. |
| 99 | + |
| 100 | +> Early optimization is the root of all evil. -- Donald Knuth |
| 101 | +
|
| 102 | +The challenge in this project is to extend the code to support more features. The more we have, the harder it will be to maintain the code. Fancy tricks without a good reason are not good. |
| 103 | + |
| 104 | +A piece code that is performant, easy to read and understand, and easy to maintain is the best. [But sometime you can not have it all](https://www.youtube.com/watch?v=hFDcoX7s6rE). So, you need to choose what is more important for your case. |
0 commit comments