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
   

   View Slide

2. Gift Egwuenu
   @LAURAGIFT_
   DEVELOPER ADVOCATE, CLOUDFLARE
   

   View Slide

3. WHY DOES CLEAN CODE MATTER?
   

   View Slide

4. ✅
   A good way to keep your code maintainable?
   

   View Slide

5. ✅
   Its a good practice when you work with a large team?
   

   View Slide

6. HOW DO YOU CLASSIFY BAD CODE?
   

   View Slide

7. Shh... Code Review In Progress!
   

   View Slide

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',
   });
   

   View Slide

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',
   });
   

   View Slide

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',
    });
    

    View Slide

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',
    });
    

    View Slide

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',
    });
    

    View Slide

13. BAD CODE IS CODE THAT IS DIFFICULT TO
    UNDERSTAND AND CREATES TECHNICAL
    DEBT.
    

    View Slide

14. NO ONE UNDERSTANDS IT EXCEPT THE
    PERSON WHO WROTE IT.
    

    View Slide

15. What bad code looks like.
    

    View Slide

16. LATER = NEVER
    ⭐
    Learn more about the LeBlanc's Law.
    

    View Slide

17. Messy code in a long term causes technical debt!
    

    View Slide

18. BEST PRACTICES FOR
    WRITING CLEAN CODE
    

    View Slide

19. WHAT IS CLEAN CODE?
    

    View Slide

20. CLEAN CODE IS CODE THAT IS
    COMPREHENSIVE AND EASY TO
    UNDERSTAND.
    

    View Slide

21. Clean code always looks like it was written by
    someone who cares!
    -- Michael Feathers
    

    View Slide

22. USE MEANINGFUL NAMING
    CONVENTIONS
    

    View Slide

23. There are only two hard things in
    Computer Science: cache invalidation
    and naming things.
    — Phil Karlton
    

    View Slide

24. Who else is guilty?
    

    View Slide

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({});
    

    View Slide

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({});
    

    View Slide

27. USE PRONOUCABLE NAMES
    //
    ❌
    this is a bad example
    const yyyy = new Date('August 19, 1975 23:15:30');
    const date1 = yyyy.getDate();
    

    View Slide

28. USE PRONOUCABLE NAMES
    //
    ✅
    this is a good example
    const birthday = new Date('August 19, 1975 23:15:30');
    const date = birthday.getDate();
    

    View Slide

29. WRITE CLEAN FUNCTIONS
    

    View Slide

30. FUNCTIONS SHOULD DO ONE THING. THEY SHOULD DO IT WELL.
    THEY SHOULD DO IT ONLY.
    

    View Slide

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();
    

    View Slide

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();
    

    View Slide

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}.`);
    }
    

    View Slide

34. GOOD CODE COMMENTS
    

    View Slide

35. View Slide

36. ❌
    BAD COMMENT EXAMPLES
    

    View Slide

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',
    });
    

    View Slide

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',
    // },
    // },
    // });
    

    View Slide

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,
    );
    });
    

    View Slide

40. ✅
    GOOD COMMENT EXAMPLES
    

    View Slide

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,
    );
    });
    

    View Slide

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,
    );
    });
    

    View Slide

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,
    );
    });
    

    View Slide

44. FORMATTING / STYLE GUIDE
    

    View Slide

45. JS Standard Style, Airbnb Style Guide etc..
    

    View Slide

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 {}
    

    View Slide

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 {}
    

    View Slide

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 {}
    

    View Slide

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 {}
    

    View Slide

50. TESTING
    

    View Slide

51. LAWS OF TDD
    

    View Slide

52. LAWS OF TDD
    ▸ Write production code only to pass a failing unit test.
    

    View Slide

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).
    

    View Slide

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.
    

    View Slide

55. Good tests should follow the FIRST principle:
    F = Fast
    i = Isolated
    R = Repeatable
    S = Self Validating
    T = Timely
    

    View Slide

56. The FIRST Principle
    

    View Slide

57. ERROR HANDLING
    

    View Slide

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);
    }
    });
    

    View Slide

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);
    }
    });
    

    View Slide

60. CLEAN CODE
    PRINCIPLES
    

    View Slide

61. K.I.S.S
    KEEP IT SIMPLE, STUPID
    

    View Slide

62. D.R.Y
    DON'T REPEAT YOURSELF
    

    View Slide

63. W.E.T ( We enjoy typing!)
    

    View Slide

64. Y.A.G.N.I
    YOU AIN'T GONNA NEED IT
    

    View Slide

65. YAGNI PRINCIPLE
    

    View Slide

66. BOY'S SCOUT RULE
    

    View Slide

67. ”ALWAYS LEAVE THE CODE CLEANER THAN
    YOU FOUND IT”
    

    View Slide

68. HOW YOU CAN TELL YOUR CODE IS CLEAN?
    

    View Slide

69. HOW YOU CAN TELL YOUR CODE IS CLEAN?
    ▸ Can someone else read this and understand what I wrote?
    

    View Slide

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?
    

    View Slide

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?
    

    View Slide

72. RECAP
    

    View Slide

73. BEST PRACTICES FOR WRITING CLEAN CODE
    

    View Slide

74. BEST PRACTICES FOR WRITING CLEAN CODE
    ▸ Use meaningful naming conventions
    

    View Slide

75. BEST PRACTICES FOR WRITING CLEAN CODE
    ▸ Use meaningful naming conventions
    ▸ Write clean functions
    

    View Slide

76. BEST PRACTICES FOR WRITING CLEAN CODE
    ▸ Use meaningful naming conventions
    ▸ Write clean functions
    ▸ Good code comments
    

    View Slide

77. BEST PRACTICES FOR WRITING CLEAN CODE
    ▸ Use meaningful naming conventions
    ▸ Write clean functions
    ▸ Good code comments
    ▸ Format and use a style guide
    

    View Slide

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
    

    View Slide

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
    

    View Slide

80. CLEAN CODE PRINCIPLES
    

    View Slide

81. CLEAN CODE PRINCIPLES
    ▸ K.I.S.S
    

    View Slide

82. CLEAN CODE PRINCIPLES
    ▸ K.I.S.S
    ▸ D.R.Y
    

    View Slide

83. CLEAN CODE PRINCIPLES
    ▸ K.I.S.S
    ▸ D.R.Y
    ▸ Y.A.G.N.I
    

    View Slide

84. CLEAN CODE PRINCIPLES
    ▸ K.I.S.S
    ▸ D.R.Y
    ▸ Y.A.G.N.I
    ▸ Boy's Scout Rule
    

    View Slide

85. REMEMBER:
    "ALWAYS LEAVE THE CODE CLEANER THAN
    YOU FOUND IT"
    

    View Slide

86. WHAT TO DO NEXT?
    

    View Slide

87. RESOURCES
    

    View Slide

88. RESOURCES
    ▸ Clean Code Book - Robert Martin
    

    View Slide

89. RESOURCES
    ▸ Clean Code Book - Robert Martin
    ▸ Code Complete - Steve McConnell
    

    View Slide

90. RESOURCES
    ▸ Clean Code Book - Robert Martin
    ▸ Code Complete - Steve McConnell
    ▸ Introduction to Clean Code and Software Design Principles
    

    View Slide

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
    

    View Slide

92. Thank you!
    @LAURAGIFT_
    

    View Slide