$30 off During Our Annual Pro Sale. View Details »

Writing Clean Code for Humans

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.

Egwuenu Gift

April 20, 2022
Tweet

More Decks by Egwuenu Gift

Other Decks in Programming

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

  35. None
  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_