Writing HUMAN READABLE CODE

1. Poul Ryste Hansen Pocket PlayLab prh@bbdt.com Writing HUMAN READABLE CODE

2. About me Name: Poul Ryste Hansen Nationality: Danish Age: 38 Lived in Thailand since mid-february 2011 Currently working as CTO for Pocket PlayLab and BBDT.com Worked for 18 years in the Web Development industry.

3. Game development About Pocket PlayLab • We develop iOS, Android and Facebook games. • About to release our first title on iOS.

4. iOS and Web Development About BBDT.com • UX/Web design, HTML/CSS. • iOSDevelopment. • Custom Facebook, web solutions and integrations.

5. Writing Human Readable Code What is Human Readable Code • What do I mean by code? • So what do I mean by Human Readable?

6. Spelling, avoid typos Naming • Key idea: • Avoid spelling errors, IDE auto-completion can only help to a certain degree

7. Putting information in the names Naming • Key idea: • Let the reader instantly know what the name refers to • Choose specificwords • Avoid generic names • Use concrete names • Attach extra information • Exceptions

8. Avoid words that doesn’t convey something very specific Choose specific words

9. Avoid words that doesn’t convey something very specific Avoid generic names

10. Avoid words that doesn’t convey something very specific Use concrete names • Google C++ sample: • Argument example: • --run_locally • --loglevel_verbose_debug

11. Avoid words that doesn’t convey something very specific Attach extra information

12. Commonly used exceptions Exceptions • Using commonly accepted language name references is okay • Loop constructs i, j, k • CSS naming such as “header” • Do not use these for anything else but the commonly accepted way!

13. Avoid names that are easily misunderstood Naming • Key idea: • Look over your names and ask yourself, “What else could this name be understood as?” • Avoid ambiguity • Range limits • Watch out for booleans • Always consider pre-conceived expectations

14. Avoid ambiguity Naming

15. Range limits Naming

16. Booleans, being exact Naming

17. Pre-conceived expectations Naming • getMean() vscomputeMean(); • size() vscountSize();

18. Consistency Naming • Key idea: • Use well known naming schemes, and use them consistently through the whole project.

19. Knowing what to comment Commenting • Key idea: • You want to help the reader know as much as you did, when you wrote the code. • How: • Knowing what not to comment • Recording your thoughts as you code • Putting yourself in the readers shoes

20. Precise and compact comments Commenting • Key idea: • Put as much information in as little text as possible, but still easily readable. • How: • Avoid ambiguity. • Be precise. • State your intent.

21. Describe logic clearly From idea to code • Key idea: • Describe code logic clearly, to emphasize what it does. • Comment logic • Use plain English

22. Beautifying your code Aesthetics • Key idea: • Make your code easier to read through formatting of the text.

23. If you don’t need it, don’t do it Writing less code • Key idea: • Adding functionality that you might use some day, will just make it harder to understand now.

24. Keep your codebase small Writing less code • Key idea: • The most readable code, is no code at all. • How: • Remove duplicate code. • Remove unused code. • Refactor.

25. Refactoring and re-usage Writing less code • Key idea: • Clean up your “hard to read code” when possible. • Wikipedia definition: • Code refactoring is a "disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior"

26. Small tasks One task at a time • Key idea: • Code should be organized so that it does only one thing at a time. • How: • Line out all the tasks • Keep tasks small and focused

27. Extracting unrelated sub-problems Focus on one problem domain • Key idea: • Keep your code focused on the main problem domain, extract non-related-code if it hinders the readability. • How: • Look at a method or code block, then ask, “What is the high-level goal of this?” • For each line of code, ask, “Is it working directly to that goal? Or is it solving an unrelated sub-problem needed to meet it?” • If enough lines are solving an unrelated sub-problem, extract that code into a separate function.

28. Knowing public libraries Writing less code • Key idea: • Save time and help readability, by using already created libraries that are well documented.

29. A few last words Finally • Books: • The Art of Readable Code - O´Reilly - Dustin Bosswell / Trevor Foucher • The Pragmatic Programmer: From Journeyman to Master - Addison-Wesley - Andrew Hunt / David Thomas • Good articles / blogs: • CSS coding: semantic approach in naming conventionhttp://woork.blogspot.com/2008/11/css-coding-semantic-approach-in-naming.html • CSS Tip #2: Structural Naming Convention in CSShttp://sixrevisions.com/css/css-tips/css-tip-2-structural-naming-convention-in-css/ • Top 15+ Best Practices for Writing Super Readable Codehttp://net.tutsplus.com/tutorials/html-css-techniques/top-15-best-practices-for-writing-super-readable-code/ • How to write readable code? 5 Tips to improve your code readability http://www.makinggoodsoftware.com/2009/06/22/how-to-write-readable-code/