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.

5943abec14734639dd5ad75e437639d3?s=128

Miguel Laginha

June 03, 2018
Tweet

Transcript

  1. A CASE FOR EXPLICITNESS IN OPEN SOURCE

  2. HI, MY NAME IS MIGUEL

  3. EXPLICITNESS?!

  4. BE EXPLICIT

  5. 1 EXPLICIT COMMENTS

  6. WHAT VS WHY

  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 */
  8. 2 EXPLICIT CODE

  9. IMPLICIT VS EXPLICIT

  10. DON'T BE EVIL MAGIC

  11. NOT EVERYONE IS A SENIOR BE BEGINNER FRIENDLY

  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);
  13. 3 EXPLICIT DOCUMENTATION

  14. DOCUMENTATION IS AN EMPATHY EXERCISE

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

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

  17. MAIN TAKEAWAY !

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

  19. ! THANK YOU