![4.Hard to Follow Flow of Execution
Functions that return arbitrary data:
$monster_array = $book->process_authors();
print $monster_array[0]['author']['first_name'];](https://image.slidesharecdn.com/14207985-120907164326-phpapp01/85/Writing-Readable-Code-47-320.jpg)
![4.Hard to Follow Flow of Execution
Functions that return arbitrary data:
$monster_array = $book->process_authors();
print $monster_array[0]['author']['first_name'];
● Return arrays of objects instead
or an iterator
● Make a (documented) class for the
return objects
● Sample of the returned data
structure in the comment block](https://image.slidesharecdn.com/14207985-120907164326-phpapp01/85/Writing-Readable-Code-48-320.jpg)
Writing Readable Code
- 1. Writing Readable Code Eddie Haber Sr Developer, Reflexions Data Reflexions on Coding 9.7.2012
- 3. Overview 1. What is Readable Code? 2. Why is it So Important? 3. How Code Gets Unreadable 4. Patterns that Make Code Hard to Read: ● Deep Nesting ● Unnecessary Generalization ● Ambiguous Names ● Hard to Follow Flow of Execution ● Code Style vs Individualism ● Code Comments 5. Best Practices
- 4. What is Readable Code? Source: Head First Labs
- 5. What is Readable Code? Reads like natural language
- 6. What is Readable Code? Reads like natural language Spaced into digestible chunks like paragraphs
- 7. What is Readable Code? Reads like natural language Spaced into digestible chunks like paragraphs Explains Itself
- 8. What is Readable Code? Reads like natural language Spaced into digestible chunks like paragraphs Explains Itself Tells a story: The Spec
- 9. Why is it So Important?
- 10. Why is it So Important? Saves you, your team, your client time.
- 11. Why is it So Important? Saves you, your team, your client time. Memories fade with time.
- 12. Why is it So Important? Saves you, your team, your client time. Memories fade with time. Many projects go undocumented. Readable code can be documentation in itself.
- 13. Why is it So Important? Saves you, your team, your client time. Memories fade with time. Many projects go undocumented. Readable code can be documentation in itself. Fewer regression bugs.
- 14. Why is it So Important? Hard-to-read code seems more complex and harder to edit than it really is.
- 15. How Code Gets Unreadable Business logic can be arbitrary, complex, even contradictory.
- 16. How Code Gets Unreadable Polluted over time Cruft Inefficient edits
- 17. Software applications are the most complex man-made constructs in existence. Source: scottmccloud.com
- 18. Patterns that Make Code Hard to Read · Deep Nesting · Unnecessary Generalization · Ambiguous Names · Hard to Follow Flow of Execution · Code Style vs Individualism · Code Comments
- 19. 1.Deep Nesting Patterns that Make Code Hard to Read
- 20. 4. Patterns: Deep Nesting
- 27. 1.Deep Nesting Nesting is hard to read and edit. Return early from loops and functions. Use continue, break, return. Meat of function ideally at first level of indentation
- 28. 2.Unnecessary Generalization Patterns that Make Code Hard to Read
- 29. 2.Unnecessary Generalization Never abstract for a single implementation.
- 30. 2.Unnecessary Generalization Never abstract for a single implementation. // 10 lines of code // that calls a // gateway once vs // a gateway class // with a single // implementation
- 31. 3.Ambiguous Names Patterns that Make Code Hard to Read
- 32. 3.Ambiguous Names Is that string you're about to use to query authors from a SQL table a... $qry $sql $search $select $author_qry $authors_sql $db_query $query_authors
- 33. 3.Ambiguous Names Is the result that comes back a... $search $dbh $authors_list $rslt $author_result $response $results $auth_dbh
- 34. 3.Ambiguous Names Be consistent. Use clear simple naming. $db = new Database_Adapter(); $sql = "SELECT * FROM authors"; $result = $db->query($sql); $sql (goes to) $db (delivers) $result
- 35. 3.Ambiguous Names Sneaky Boolean Variables... if ($fail_gateway)... Is it true if failed, or false if failed?
- 36. 3.Ambiguous Names Mysterious Boolean Parameters... send_mail($recipients, $msg, true);
- 37. 3.Ambiguous Names Mysterious Boolean Parameters... send_mail($recipients, $msg, true); Use constants (they're free!) to make codeflow readable... const('DELETE_ALL_ACCOUNTS', true); const('DO_NOT_DELETE_ACCOUNTS', false); send_mail($recipients, $msg, DELETE_ALL_ACCOUNTS);
- 38. 3.Ambiguous Names Avoid excessive abbreviation. Abbreviations are arbitrary and hard to remember.
- 39. 3.Ambiguous Names Avoid excessive abbreviation. Abbreviations are arbitrary and hard to remember. $srchBttn ? Was it... $searchBtn ? $schBtn ? $srchBtn ? Be explicit. $search_button
- 40. 4.Hard to Follow Flow of Execution Patterns that Make Code Hard to Read
- 41. 4.Hard to Follow Flow of Execution Reading code means following the flow of execution.
- 42. 4.Hard to Follow Flow of Execution Transitional variables $string = "Three Card Monte"; $lowercase = strtolower($string); $ready_for_web = htmlentities($lowercase); $view->name = $ready_for_web;
- 43. 4.Hard to Follow Flow of Execution Transitional variables $string = "Three Card Monte"; $lowercase = strtolower($string); $ready_for_web = htmlentities($lowercase); $view->name = $ready_for_web; Less code = Less reading $string = "Three Card Monte"; $view->name = htmlentities(strtolower($string));
- 44. 4.Hard to Follow Flow of Execution Status codes and ids in code are mysteries. $order->set_order_type(5);
- 45. 4.Hard to Follow Flow of Execution Status codes and ids in code are mysteries. $order->set_order_type(5); Use strings or constants for concrete statuses. $order->update_status(OrderStatus::PAID);
- 46. 4.Hard to Follow Flow of Execution Status codes and ids in code are mysteries. $order->set_order_type(5); Use strings or constants for concrete statuses. $order->update_status(OrderStatus::PAID); Reference concrete data by string $sql = "SELECT * FROM role WHERE id = 1"; $sql = "SELECT * FROM role WHERE role = 'admin';
- 47. 4.Hard to Follow Flow of Execution Functions that return arbitrary data: $monster_array = $book->process_authors(); print $monster_array[0]['author']['first_name'];
- 48. 4.Hard to Follow Flow of Execution Functions that return arbitrary data: $monster_array = $book->process_authors(); print $monster_array[0]['author']['first_name']; ● Return arrays of objects instead or an iterator ● Make a (documented) class for the return objects ● Sample of the returned data structure in the comment block
- 49. 5.Code Style vs. Individualism Patterns that Make Code Hard to Read
- 50. 5.Code Style vs. Individualism Camelcase or underscore? Curly braces with or without conditionals? Use the formats and conventions of the language or framework you're working with.
- 51. 5.Code Style vs. Individualism Funny variable names, comments, and methods. Just make sure they explain functionality. $dull_boy = work_all_day($Jack_Torrence);
- 52. 5.Code Style vs. Individualism Whitespace is crucially important even when the compiler doesn't mind. ● If tabs, stay with tabs ● If spaces, stay with spaces ● Indent consistently - indentation is a queue for reading
- 53. 6.Code Comments Patterns that Make Code Hard to Read
- 54. 6.Code Comments Helpful vs. unhelpful comments // ping the server // ping server to make $results = ping($server); // sure still running and // log results // check the results vs. $results = ping($server); check_results($results); check_results($results); log_results($results); // log the results exit; log_results($results); // exit exit;
- 55. 6.Code Comments Who are you talking to? Avoid unhelpful questions in comments // Why is this even here? Make comments clear and useful // Magic. Do not touch.
- 56. 6.Code Comments Use DocBlock style blocks... ● Over all functions/methods ● Define @params and @returns ● If business rules involved, give a synopsis of what the method does.
- 57. 6.Code Comments Source: NetTutsPlus
- 58. Best Practices
- 59. Best Practices Refactor! The first pass is usually the least efficient implementation. ● Jeuje code ● Transitional variables ● Return early ● Add comments
- 60. Best Practices Break down large tasks into smaller ones. ● More private and protected "helper" methods. ● Objects format and filter their own output.
- 61. Best Practices DRY - Don't Repeat Yourself. Use libraries and conventions already established ● In the class (method already exists?) ● In the libs (utility already exists?) ● In the framework (component already exists?) ● On the web (website already exists?)
- 62. // // Dear maintainer: // // Once you are done trying to 'optimize' this routine, // and have realized what a terrible mistake that was, // please increment the following counter as a warning // to the next guy: // // total_hours_wasted_here = 42 // Reflexions on Coding 9.7.2012