A case for explicitness in open source

Why I should we should strive to be explicit in open source projects, in order to be beginner friendly and attract a wider community.

Transcript

1. A CASE FOR
   EXPLICITNESS
   IN OPEN SOURCE
   

   View Slide

2. HI, MY NAME IS MIGUEL
   

   View Slide

3. EXPLICITNESS?!
   

   View Slide

4. BE
   EXPLICIT
   

   View Slide

5. 1 EXPLICIT
   COMMENTS
   

   View Slide

6. WHAT VS WHY
   

   View Slide

7. EXAMPLE
   /**
   * An object that represents a target for a share / role change. There are 3 different permutations
   * that have slightly different meanings:
   *
   * * Only `principal` is set: The target for the share is some principal (user or group) and the
   * appropriate interaction checks should be performed for the target
   * * Only `email` is set: The target is an email invitation
   * * Both `principal` and `email` are set: If the email matches the email of the principal
   * profile, then interaction checks can be bypassed as the client has successfully
   * looked up the user by email
   *
   * A `role` can optionally be present with the target, indicating a role change to apply to the
   * target
   *
   * @param {Principal} [principal] The principal profile
   * @param {String} [email] The email address
   * @param {String} [role] The role change to apply, if applicable
   */
   

   View Slide

8. 2 EXPLICIT
   CODE
   

   View Slide

9. IMPLICIT VS EXPLICIT
   

   View Slide

10. DON'T BE EVIL MAGIC
    

    View Slide

11. NOT EVERYONE IS A SENIOR
    BE BEGINNER FRIENDLY
    

    View Slide

12. STRIVE FOR READABLE
    // function composition example
    const scream = str => str.toUpperCase();
    const exclaim = str => `${str}!`;
    const repeat = str => `${str} ${str}`;
    const string = "Open Apereo is awesome!";
    // approach A
    const result = repeat(exclaim(scream(string)));
    // approach B
    const compose = (...fns) => x =>
    fns.reduceRight((acc, fn) => fn(acc, x)
    const enhance = compose(repeat, exclaim, scream);
    const result = enhance(string);
    

    View Slide

13. 3 EXPLICIT
    DOCUMENTATION
    

    View Slide

14. DOCUMENTATION IS
    AN EMPATHY EXERCISE
    

    View Slide

15. IT'S HAPPENED TO YOU
    DON'T LET IT HAPPEN TO OTHERS
    

    View Slide

16. NORMAL BEHAVIOUR, EDGE CASES,
    ERRORS THROWN, RATIONALE,
    ACCESSIBLE LANGUAGE
    

    View Slide

17. MAIN TAKEAWAY
    !
    

    View Slide

18. LET'S PRODUCE EXPLICIT
    OPEN SOURCE CODE / COMMENTS / DOCUMENTATION
    

    View Slide

19. !
    THANK YOU
    

    View Slide