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

A case for explicitness in open source

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.

Miguel Laginha

June 03, 2018
Tweet

More Decks by Miguel Laginha

Other Decks in Programming

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