Writing Clean Code for Humans

Have you ever wondered why you constantly have difficulty understanding your code months or years later, or how difficult it is for others to understand your code? Every developer should be able to write clean, easy-to-understand code. My talk will discuss a few bad coding practices we often overlook that can quickly cause problems for you and your team, and how you can avoid them.

Transcript

1. WRITING CLEAN CODE FOR HUMANS Women Coding The Future - Online, April 2022
2. Gift Egwuenu @LAURAGIFT_ DEVELOPER ADVOCATE, CLOUDFLARE
3. WHY DOES CLEAN CODE MATTER?
4. ✅ A good way to keep your code maintainable?
5. ✅ Its a good practice when you work with a large team?
6. HOW DO YOU CLASSIFY BAD CODE?
7. Shh... Code Review In Progress!
8. WHAT'S WRONG WITH THIS CODE? // sending get request to Shopify Admin API const x = await Shopify.Utils.loadCurrentSession(req, res); const y = new Shopify.Clients.Rest(x.shop, x.accessToken); const products = await y.get({ path: 'products', });
9. WHAT'S WRONG WITH THIS CODE? // sending get request to Shopify Admin API const x = await Shopify.Utils.loadCurrentSession(req, res); const y = new Shopify.Clients.Rest(x.shop, x.accessToken); const products = await y.get({ path: 'products', });
10. WHAT'S WRONG WITH THIS CODE? // sending get request to Shopify Admin API const x = await Shopify.Utils.loadCurrentSession(req, res); const y = new Shopify.Clients.Rest(x.shop, x.accessToken); const products = await y.get({ path: 'products', });
11. WHAT'S WRONG WITH THIS CODE? // sending get request to Shopify Admin API const x = await Shopify.Utils.loadCurrentSession(req, res); const y = new Shopify.Clients.Rest(x.shop, x.accessToken); const products = await y.get({ path: 'products', });
12. BETTER EXAMPLE // sending get request to Shopify Admin API const session = await Shopify.Utils.loadCurrentSession(req, res); const client = new Shopify.Clients.Rest(session.shop, session.accessToken); const products = await client.get({ path: 'products', });
13. BAD CODE IS CODE THAT IS DIFFICULT TO UNDERSTAND AND CREATES TECHNICAL DEBT.
14. NO ONE UNDERSTANDS IT EXCEPT THE PERSON WHO WROTE IT.
15. What bad code looks like.
16. LATER = NEVER ⭐ Learn more about the LeBlanc's Law.
17. Messy code in a long term causes technical debt!
18. BEST PRACTICES FOR WRITING CLEAN CODE
19. WHAT IS CLEAN CODE?
20. CLEAN CODE IS CODE THAT IS COMPREHENSIVE AND EASY TO UNDERSTAND.
21. Clean code always looks like it was written by someone who cares! -- Michael Feathers
22. USE MEANINGFUL NAMING CONVENTIONS
23. There are only two hard things in Computer Science: cache invalidation and naming things. — Phil Karlton
24. Who else is guilty?
25. USE INTENTIONAL- REVEALING NAMES // ❌ this is a bad example import { Order } from '@shopify/shopify-api/dist/rest-resources/2022-04/index.js'; const x = await Shopify.Utils.loadCurrentSession(request, response); const y = new Order({session: x }); y.id = 450789469; await y.cancel({});
26. USE INTENTIONAL- REVEALING NAMES // ✅ this is a good example import {Order} from '@shopify/shopify-api/dist/rest-resources/2022-04/index.js'; const current_session = await Shopify.Utils.loadCurrentSession(request, response); const order = new Order({session: current_session}); order.id = 450789469; await order.cancel({});
27. USE PRONOUCABLE NAMES // ❌ this is a bad example const yyyy = new Date('August 19, 1975 23:15:30'); const date1 = yyyy.getDate();
28. USE PRONOUCABLE NAMES // ✅ this is a good example const birthday = new Date('August 19, 1975 23:15:30'); const date = birthday.getDate();
29. WRITE CLEAN FUNCTIONS
30. FUNCTIONS SHOULD DO ONE THING. THEY SHOULD DO IT WELL. THEY SHOULD DO IT ONLY.
31. FUNCTION SHOULD DO JUST ONE THING // ❌ this is a bad example function getCustomer(customer) { const customerName = prompt("What is your name?"); console.log(`Hello ${customerName}! How are you?`); const customerAddress = prompt("What is your address?"); console.log(`My address is: ${customerAddress}.`); } return getCustomer();
32. FUNCTION SHOULD DO JUST ONE THING // ❌ this is a bad example function getCustomer(customer) { const customerName = prompt("What is your name?"); console.log(`Hello ${customerName}! How are you?`); const customerAddress = prompt("What is your address?"); console.log(`My address is: ${customerAddress}.`); } return getCustomer();
33. FUNCTION SHOULD DO JUST ONE THING // ✅ this is a good example function getCustomerName(customer) { const customerName = prompt("What is your name?"); console.log(`Hello ${customerName}! How are you?`); } function getCustomerAddress(customer) { const customerAddress = prompt("What is your address?"); console.log(`My address is: ${customerAddress}.`); }
34. GOOD CODE COMMENTS
36. ❌ BAD COMMENT EXAMPLES
37. NEVER EXPLAIN WHAT THE CODE IS DOING // Load the current session to get the `accessToken`. const session = await Shopify.Utils.loadCurrentSession(req, res); // Create a new client for the specified shop. const client = new Shopify.Clients.Rest(session.shop, session.accessToken); // Use `client.get` to request the specified Shopify REST API endpoint, in this case `products`. const products = await client.get({ path: 'products', });
38. REMOVE COMMENTED CODE const adminApiClient = new Shopify.Clients.Rest( session.shop, session.accessToken, ); // const storefrontTokenResponse = await adminApiClient.post({ // path: 'storefront_access_tokens', // type: DataType.JSON, // data: { // storefront_access_token: { // title: 'This is my test access token', // }, // }, // });
39. AVOID JOURNAL COMMENTS /** * 2022-04-20: Removed call to GraphQL Endpoint, will do that later (GE) * 2022-04-01: Improved Code Quality (JP) */ const storefrontAccessToken: string; const session = await Shopify.Utils.loadCurrentSession(req, res); // StorefrontClient takes in the shop url and the Storefront Access Token for that shop. const client = new Shopify.Clients.Storefront( session.shop, storefrontAccessToken, ); });
40. ✅ GOOD COMMENT EXAMPLES
41. LEGAL COMMENTS /* @licstart Copyright (©) 2022 CompanyName Available under the terms of the GNU/LGPL-3.0 See LICENSE file for more informations. @licend */ const storefrontAccessToken: string; const session = await Shopify.Utils.loadCurrentSession(req, res); const client = new Shopify.Clients.Storefront( session.shop, storefrontAccessToken, ); });
42. JSDOC COMMENTS /** * Storefront POST API * @constructor * @param {object} req - The request object * @param {object} res - The response object */ const storefrontAccessToken: string; const session = await Shopify.Utils.loadCurrentSession(req, res); const client = new Shopify.Clients.Storefront( session.shop, storefrontAccessToken, ); });
43. TODO COMMENTS // TODO: Implement request to GraphQL endpoint const storefrontAccessToken: string; const session = await Shopify.Utils.loadCurrentSession(req, res); const client = new Shopify.Clients.Storefront( session.shop, storefrontAccessToken, ); });
44. FORMATTING / STYLE GUIDE
45. JS Standard Style, Airbnb Style Guide etc..
46. FOLLOW CONSISTENT STYLE // ❌ this is a bad example const DAYS_IN_WEEK = 7; const daysInMonth = 30; function getUserData() {} function delete_user_data() {} class user {} class Account {}
47. FOLLOW CONSISTENT STYLE // ✅ this is a good example const DAYS_IN_WEEK = 7; const DAYS_IN_MONTH = 30; function getUserData() {} function deleteUserData() {} class User {} class Account {}
48. FOLLOW CONSISTENT STYLE // ✅ this is a good example const DAYS_IN_WEEK = 7; const DAYS_IN_MONTH = 30; function getUserData() {} function deleteUserData() {} class User {} class Account {}
49. FOLLOW CONSISTENT STYLE // ✅ this is a good example const DAYS_IN_WEEK = 7; const DAYS_IN_MONTH = 30; function getUserData() {} function deleteUserData() {} class User {} class Account {}
50. TESTING
51. LAWS OF TDD
52. LAWS OF TDD ▸ Write production code only to pass a failing unit test.
53. LAWS OF TDD ▸ Write production code only to pass a failing unit test. ▸ Write no more of a unit test than sufficient to fail (compilation failures are failures).
54. LAWS OF TDD ▸ Write production code only to pass a failing unit test. ▸ Write no more of a unit test than sufficient to fail (compilation failures are failures). ▸ Write no more production code than necessary to pass the one failing unit test.
55. Good tests should follow the FIRST principle: F = Fast i = Isolated R = Repeatable S = Self Validating T = Timely
56. The FIRST Principle
57. ERROR HANDLING
58. BAD CODE: ERROR HANDLING WITH TRY, CATCH EXPECTIONS app.post('/webhooks', async (req, res) => { try { await Shopify.Webhooks.Registry.process(req, res); } catch (error) { // ❌ this is not sufficient console.log(error); } });
59. GOOD CODE: ERROR HANDLING WITH TRY, CATCH EXPECTIONS app.post('/webhooks', async (req, res) => { try { await Shopify.Webhooks.Registry.process(req, res); } catch (error) { // ✅ this is better console.log(error); notifyUserOfError(error); reportErrortoService(error); } });
60. CLEAN CODE PRINCIPLES
61. K.I.S.S KEEP IT SIMPLE, STUPID
62. D.R.Y DON'T REPEAT YOURSELF
63. W.E.T ( We enjoy typing!)
64. Y.A.G.N.I YOU AIN'T GONNA NEED IT
65. YAGNI PRINCIPLE
66. BOY'S SCOUT RULE
67. ”ALWAYS LEAVE THE CODE CLEANER THAN YOU FOUND IT”
68. HOW YOU CAN TELL YOUR CODE IS CLEAN?
69. HOW YOU CAN TELL YOUR CODE IS CLEAN? ▸ Can someone else read this and understand what I wrote?
70. HOW YOU CAN TELL YOUR CODE IS CLEAN? ▸ Can someone else read this and understand what I wrote? ▸ How easy is it going to be to add new features further down the line?
71. HOW YOU CAN TELL YOUR CODE IS CLEAN? ▸ Can someone else read this and understand what I wrote? ▸ How easy is it going to be to add new features further down the line? ▸ Do you constantly break existing functionality when making changes?
72. RECAP
73. BEST PRACTICES FOR WRITING CLEAN CODE
74. BEST PRACTICES FOR WRITING CLEAN CODE ▸ Use meaningful naming conventions
75. BEST PRACTICES FOR WRITING CLEAN CODE ▸ Use meaningful naming conventions ▸ Write clean functions
76. BEST PRACTICES FOR WRITING CLEAN CODE ▸ Use meaningful naming conventions ▸ Write clean functions ▸ Good code comments
77. BEST PRACTICES FOR WRITING CLEAN CODE ▸ Use meaningful naming conventions ▸ Write clean functions ▸ Good code comments ▸ Format and use a style guide
78. BEST PRACTICES FOR WRITING CLEAN CODE ▸ Use meaningful naming conventions ▸ Write clean functions ▸ Good code comments ▸ Format and use a style guide ▸ Follow TDD principles
79. BEST PRACTICES FOR WRITING CLEAN CODE ▸ Use meaningful naming conventions ▸ Write clean functions ▸ Good code comments ▸ Format and use a style guide ▸ Follow TDD principles ▸ Handle errors correctly
80. CLEAN CODE PRINCIPLES
81. CLEAN CODE PRINCIPLES ▸ K.I.S.S
82. CLEAN CODE PRINCIPLES ▸ K.I.S.S ▸ D.R.Y
83. CLEAN CODE PRINCIPLES ▸ K.I.S.S ▸ D.R.Y ▸ Y.A.G.N.I
84. CLEAN CODE PRINCIPLES ▸ K.I.S.S ▸ D.R.Y ▸ Y.A.G.N.I ▸ Boy's Scout Rule
85. REMEMBER: "ALWAYS LEAVE THE CODE CLEANER THAN YOU FOUND IT"
86. WHAT TO DO NEXT?
87. RESOURCES
88. RESOURCES ▸ Clean Code Book - Robert Martin
89. RESOURCES ▸ Clean Code Book - Robert Martin ▸ Code Complete - Steve McConnell
90. RESOURCES ▸ Clean Code Book - Robert Martin ▸ Code Complete - Steve McConnell ▸ Introduction to Clean Code and Software Design Principles
91. RESOURCES ▸ Clean Code Book - Robert Martin ▸ Code Complete - Steve McConnell ▸ Introduction to Clean Code and Software Design Principles ▸ Writing Clean Code for Humans - Cory House
92. Thank you! @LAURAGIFT_