CICONF 2012 - Don't Make Me Read Your Mind

1,099 views
989 views

Published on

Published in: Technology
0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,099
On SlideShare
0
From Embeds
0
Number of Embeds
167
Actions
Shares
0
Downloads
27
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • CICONF 2012 - Don't Make Me Read Your Mind

    1. 1. Dont Make Me ReadYour MindAaron KuzemchakCICONF 2012 - San Francisco, CA
    2. 2. Goal๏ To suggest best practices and tools to make your code easier and more enjoyable for future developers to understand.
    3. 3. About Me
    4. 4. Sr. Application Developerat Visual Chefs
    5. 5. Im from Richmond, VA
    6. 6. I have an awesome family
    7. 7. Former full-timefront-end developer
    8. 8. I ♥ PHP
    9. 9. I build...๏ Websites with ExpressionEngine๏ Web applications with CodeIgniter & Laravel
    10. 10. My info๏ http://kuzemchak.net/๏ https://github.com/akuzemchak๏ @akuzemchak
    11. 11. About Visual Chefs
    12. 12. Also known as "eecoder"
    13. 13. Also from Richmond, VA
    14. 14. We rock ExpressionEngine
    15. 15. We also rock CodeIgniter
    16. 16. Our info๏ http://www.visualchefs.com/๏ http://eecoder.com/๏ @eecoder
    17. 17. Overview1.Writing documentation2.Organization & planning3.Tools to help
    18. 18. "Documentation! Im soexcited!" you all say
    19. 19. Its important if anyone elsewill ever look at your code
    20. 20. And it can always be donebetter
    21. 21. And if you dont do it...
    22. 22. Bad thingsawait youTrust me, you want todocument
    23. 23. Nothing revolutionary
    24. 24. KYA:Keep You Accountable
    25. 25. KYA:Kick Your Ass
    26. 26. Documentation
    27. 27. Thats documentation inyour code, not end-user
    28. 28. Everything you write shouldbe documented
    29. 29. I cant read your mindAha! Thats where the presentation title comes from!
    30. 30. You and I dont see thingsthe same way
    31. 31. Dont assume Im goodenough to learn from yourcode
    32. 32. Dont assume your codeis good enough to teach
    33. 33. Document first
    34. 34. Use your comments toguide you
    35. 35. // ------------------------------------------------------------// User Login// ------------------------------------------------------------ // If the credentials were correct, login and redirect to dashboard // Otherwise, redirect to the login form with errors
    36. 36. // ------------------------------------------------------------// User Login// ------------------------------------------------------------ // If the credentials were correct, login and redirect to dashboardif($this->auth->login($email, $password) === TRUE){    redirect(account/dashboard);}// Otherwise, redirect to the login form with errorselse{    $this->session->set_userdata(errors, $this->auth->errors);    redirect(login);}
    37. 37. Comment major controlstructures
    38. 38. ๏ Classes ๏ Properties ๏ Methods๏ Functions๏ Most conditionals๏ Most loops
    39. 39. Tag your comments
    40. 40. // @TODO:  Handle failed API requests better// @NOTE:  Passing by reference is necessary here// @HACK:  Fixed minor bug in query builder// @SEE:   http://tinyurl.com/2g9mqh// @BLAME: Alex royally screwed this up
    41. 41. Write good docblocks
    42. 42. /** * login */public function login($email, $password){    // @TODO}
    43. 43. NO!/** * login */public function login($email, $password){    // @TODO}
    44. 44. Good docblocks tell you:๏ What it is๏ What it does๏ What it accepts๏ What it returns
    45. 45. Enables code hinting insome IDEs
    46. 46. Allows easydocumentation generation
    47. 47. Classes should describeauthor and meta info
    48. 48. /** * User account model * * @author     Aaron Kuzemchak * @copyright  2012 Aaron Kuzemchak * @link       http://kuzemchak.net/ * @package     CodeIgniter * @subpackage  Models */class User_model extends CI_Model{    // @TODO}
    49. 49. Methods should have morefunctional info
    50. 50. /** * Hashes an array of settings for easy storage in a database * * @param   array   $data * @return  string */public static function hash_settings($data){    return base64_encode(serialize($data));}
    51. 51. Properties should brieflydescribe the purpose andtype
    52. 52. /** * The users email address * * @var  string */public $email;
    53. 53. Put example usage in thedocblock
    54. 54. /** * Hashes an array of settings for easy storage in a database * * <code> *     $settings = MyClass::hash_settings($data_array); * </code> * * @param   array   $data * @return  string */public static function hash_settings($data){    return base64_encode(serialize($data));}
    55. 55. Use type hinting with yourarguments
    56. 56. /** * Hashes an array of settings for easy storage in a database * * <code> *     $settings = MyClass::hash_settings($data_array); * </code> * * @param   array   $data * @return  string */public static function hash_settings(array $data){    return base64_encode(serialize($data));}
    57. 57. Dont be afraid to beverbose
    58. 58. // At this point we need to send an email to the user to confirm// their purchase. Since its an HTML email, weve stored it in a// view, and can pass the necessary data to it.$email = $this->load->view(emails/receipt, $data, TRUE);
    59. 59. Reference ticket numbers,user stories, etc.
    60. 60. Because most customer"logic" doesnt make sense
    61. 61. // At this point we send an email reminder to the customer, informing them// that their subscription will expire soon. // However, dont send an email if today is a Monday or Thursday, because// the clients "really tech-saavy" cousin told them that people dont// read their email on those days. // @SEE: Ticket #138 - http://projects.visualchefs.com/tickets/138
    62. 62. Functions should havedescriptive names
    63. 63. And, they shouldnt try to dotoo much
    64. 64. /** * Get the number of comments for a user * * @param   int  $user_id * @return  int */public function comment_count($user_id){    // @TODO} /** * Get a users comments * * @param   int    $user_id * @param   int    $limit * @return  array */public function comments($user_id, $limit = 100){    // @TODO}
    65. 65. /** * Get a users comments, or just a count of their comments. * * @param   int        $user_id * @param   int        $limit * @param   bool       $count_only * @return  int|array */public function comments($user_id, $limit = 100, $count_only = FALSE){    // @NOTE: Its difficult to tell what the function does by its name    // @NOTE: It also does too many things    // @NOTE: I cant remember what the parameters are}
    66. 66. /** meh... * Get a users comments, or just a count of their comments. * * @param   int        $user_id * @param   int        $limit * @param   bool       $count_only * @return  int|array */public function comments($user_id, $limit = 100, $count_only = FALSE){    // @NOTE: Its difficult to tell what the function does by its name    // @NOTE: It also does too many things    // @NOTE: I cant remember what the parameters are}
    67. 67. CodeIgniters query builderis a great example
    68. 68. $results = $this->db->select(id, email)    ->where(plan_id, 1)    ->order_by(id, ASC)    ->limit(10)    ->get(users);
    69. 69. Reference docs for third-party tools
    70. 70. // Set the value in Redis if it doesnt already exist// @SEE: http://redis.io/commands/setnx
    71. 71. Summary๏ Documentation is easier when done first๏ Give as much insight as you can๏ Write those friggin docblocks!๏ Be verbose๏ Link to external docs when possible
    72. 72. Organization
    73. 73. MVC has made this easier
    74. 74. Have a plan
    75. 75. Write a technical orbehavioral document
    76. 76. Sample1. User fills out the registration form2. User clicks submit3. Form is submitted via Ajax 1. Form data is validated 1. If valid, account is created 2. JSON response is returned with success flag, and array of errors if invalid data4. If successful, user is redirected to the dashboard 1. If not successful, list of errors are shown
    77. 77. Helps others get a visualdescription of whatshappening
    78. 78. Simplicity is alwaysappreciated
    79. 79. Dont over-engineer things
    80. 80. Keep a README file
    81. 81. Youre probably alreadydoing this if you use Githubor Bitbucket
    82. 82. List technical requirements &setup instructions
    83. 83. REQUIREMENTS============* PHP 5.3+ * curl * mcrypt * pdo_mysql * mongo PECL extension* MySQL 5.4+* MongoDB* Redis
    84. 84. SETUP INSTRUCTIONS==================1. Create a MySQL database.2. Update settings in local database config file.3. Run database migrations from the command line.
    85. 85. Point out non-obviouschanges/tweaks/hacks
    86. 86. APPLICATION NOTES=================* Default timezone is set in index.php so that I dont have to rely on CIs odd localization system.
    87. 87. Note third-party tools youare using
    88. 88. THIRD-PARTY TOOLS=================* dompdf - http://code.google.com/p/dompdf
    89. 89. Use a style guide
    90. 90. Makes it easier to get newdevs acquainted
    91. 91. CodeIgniters is a greatstarting point
    92. 92. PSR-1 isnt bad eitherUnless you despise camelCase
    93. 93. Use the third_party folder
    94. 94. Prevents needing toseparate related configs,libraries, models, etc.
    95. 95. third_party auth config auth.php libraries auth.php models user_model.php
    96. 96. $this->load->add_package_path(APPPATH.third_party/auth);$this->load->library(auth);$this->load->model(user_model);
    97. 97. Manage CodeIgniterpackages with Sparks
    98. 98. Similar benefits to using thethird_party folder
    99. 99. Manage other dependencieswith Composer
    100. 100. Useful for any PHP project!
    101. 101. Write tests
    102. 102. Yes, unit tests
    103. 103. But, how about browser-scripted tests as well?
    104. 104. You can watch interactions,and make sure youre notbreaking stuff
    105. 105. Keep them updated whenthings change!
    106. 106. Summary๏ Have a plan๏ Simplicity๏ Keep a README file๏ Use a style guide๏ Keep packages organized with tools like Sparks and Composer๏ Write tests
    107. 107. Tools
    108. 108. Sparks
    109. 109. Makes managingCodeIgniter packages supereasy
    110. 110. cd project-rootphp -r "$(curl -fsSL http://getsparks.org/go-sparks)"php tools/spark install ion_auth
    111. 111. $this->load->spark(ion_auth/2.3.2);if( ! $this->ion_auth->logged_in()){    redirect(login);}
    112. 112. Its been around a while, souse if it you dont already
    113. 113. Composer
    114. 114. Awesome new dependencymanager
    115. 115. For any PHP project
    116. 116. Its not PEAR!
    117. 117. Packages are installed on aper-project basis
    118. 118. cd project-rootcurl -s https://getcomposer.org/installer | php
    119. 119. A simple JSON file controlsyour packages
    120. 120. {    "require": {        "nategood/httpful": ">=1.0"    }}
    121. 121. # the first time you runphp composer.phar install# all other timesphp composer.phar update
    122. 122. One autoloader to rulethem all!
    123. 123. // Put this in index.phprequire vendor/autoload.php; // Call a class and it will be loaded automatically$response = HttpfulRequest::get(http://eecoder.com/)->send();
    124. 124. Browse packages atpackagist.org
    125. 125. ApiGen
    126. 126. Generate documentationfrom your docblocks
    127. 127. Organized by namespacesand package/subpackage
    128. 128. Beautiful full highlightedsource browsing
    129. 129. Beautiful default theme (andyou can make your own)
    130. 130. Easy to install, easy to run
    131. 131. # download apigen to your project root (or wherever)php apigen/apigen.php -s source-folder -d destination-folder# watch the pretty progress bar!
    132. 132. Quick demo
    133. 133. Selenium IDE
    134. 134. Record tests in yourbrowser (with Firefox)
    135. 135. Not the most elegant UI
    136. 136. All the normal assertiongoodies of any other testingframework
    137. 137. Save and distribute testsuites
    138. 138. Click record and start testing
    139. 139. Thanks, thats all Ive got!๏ http://kuzemchak.net/๏ https://github.com/akuzemchak๏ @akuzemchak

    ×