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