{"id":76,"date":"2012-05-12T22:42:26","date_gmt":"2012-05-13T03:42:26","guid":{"rendered":"http:\/\/blogs.law.harvard.edu\/acts\/?p=76"},"modified":"2012-05-29T07:27:46","modified_gmt":"2012-05-29T11:27:46","slug":"writing-a-style-guide","status":"publish","type":"post","link":"https:\/\/archive.blogs.harvard.edu\/acts\/2012\/05\/12\/writing-a-style-guide\/","title":{"rendered":"Writing a Style Guide"},"content":{"rendered":"<p>I took a look at the style guides of all of the most popular frameworks.<\/p>\n<p><a href=\"http:\/\/www.yiiframework.com\/wiki\/102\/code-style\/\" title=\"Yii Style Guide\">Yii Style Guide<\/a><br \/>\n<a href=\"http:\/\/codeigniter.com\/user_guide\/general\/styleguide.html\" title=\"Codeigniter Style Guide\">Codeigniter Style Guide<\/a><br \/>\n<a href=\"http:\/\/framework.zend.com\/manual\/en\/coding-standard.coding-style.html\" title=\"Zend Style Guide\">Zend Style Guide<\/a><br \/>\n<a href=\"http:\/\/symfony.com\/doc\/current\/contributing\/code\/standards.html\" title=\"Symfony Style Guide\">Symfony Style Guide<\/a><br \/>\n<a href=\"http:\/\/book.cakephp.org\/2.0\/en\/contributing\/cakephp-coding-conventions.html\" title=\"CakePHP Style Guide\">CakePHP Style Guide<\/a><\/p>\n<p>Yii is the simplest.  They just tell you what should go in the Model, Controller and View.  I actually believe that&#8217;s the best thing when thinking of a framework as a framework, since a framework shouldn&#8217;t be telling you how to write your code, and you should never be mixing your code within the framework.  A framework is a tool, but it should be on the primary developer to decide on the style that&#8217;s right for them and their team.  However, I do understand that most of these style guides are talking about their framework as a project, which of course it is<\/p>\n<p>There are a lot of topics to consider in a style guide.  A lot of things popped up as I looked at the different style guides that I hadn&#8217;t even considered.  <\/p>\n<p>File Names<br \/>\nClass Names<br \/>\nMethod Names<br \/>\nMethod Definition<br \/>\nClass and File Names Using Common Words<br \/>\nDatabase Table Names<br \/>\nConstants<br \/>\nVariable Names<br \/>\nMember Visibility (Private \/ Protected)<br \/>\nIndentation<br \/>\nCommenting<br \/>\nControl Structures<br \/>\nThe PHP Tag<br \/>\nComparing Return Values and Typecasting<br \/>\nLogical Operators<br \/>\nDebugging Code<br \/>\nPHP Errors<br \/>\nWhitespace<br \/>\nLinebreaks<br \/>\nCompatibility<br \/>\nOne File per Class<br \/>\nBracket and Parenthetic Spacing<br \/>\nLocalized Text<br \/>\nOne Statement per Line<br \/>\nStrings (When to use Single or Double quotes)<br \/>\nSQL Queries<br \/>\nDefault Function Arguments<br \/>\nAssociative Arrays<br \/>\nUnit Tests<\/p>\n<p>Some of the style guides got so long I kind of got angry.  Trying to enforce things like whitespace, logical operators or indentation is foolish.  It&#8217;s just too much and it takes away from the things that are actually important.<\/p>\n<p>So what&#8217;s actually important?<\/p>\n<p>What&#8217;s important is what people are going to read.  Nobody wants to read through a 30 page style guide, and they won&#8217;t.  The best solution I&#8217;ve found is to have 2 style guides.  The first, important style guide is to outline the very essential rules you want for your project.  Try to keep it short enough to fit on one page so someone may actually read the whole thing.  Then, if you choose, you can have a nitty gritty style guide that outlines how you want your variables named and if you&#8217;re an indent nazi.  You can always refer back to the nitty gritty if someone is submitting code that you find repugnant.<\/p>\n<p><a href=\"https:\/\/github.com\/jazahn\/Quizmo\/wiki\/Style-Guide\">My style guide for Quizmo<\/a><br \/>\n<a href=\"https:\/\/github.com\/jazahn\/Quizmo\/wiki\/Style-Guide-X\">My nitty-gritty style guide for Quizmo<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>I took a look at the style guides of all of the most popular frameworks. Yii Style Guide Codeigniter Style Guide Zend Style Guide Symfony Style Guide CakePHP Style Guide Yii is the simplest. They just tell you what should go in the Model, Controller and View. I actually believe that&#8217;s the best thing when [&hellip;]<\/p>\n","protected":false},"author":4571,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[63924,3163],"tags":[63960,63958,63962,1029,63956,63959,63943,63961],"class_list":["post-76","post","type-post","status-publish","format-standard","hentry","category-atg","category-php","tag-cakephp","tag-code-standards","tag-codeigniter","tag-open-source","tag-style-guide","tag-symfony","tag-yii-2","tag-zend"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/archive.blogs.harvard.edu\/acts\/wp-json\/wp\/v2\/posts\/76","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/archive.blogs.harvard.edu\/acts\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/archive.blogs.harvard.edu\/acts\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/archive.blogs.harvard.edu\/acts\/wp-json\/wp\/v2\/users\/4571"}],"replies":[{"embeddable":true,"href":"https:\/\/archive.blogs.harvard.edu\/acts\/wp-json\/wp\/v2\/comments?post=76"}],"version-history":[{"count":8,"href":"https:\/\/archive.blogs.harvard.edu\/acts\/wp-json\/wp\/v2\/posts\/76\/revisions"}],"predecessor-version":[{"id":158,"href":"https:\/\/archive.blogs.harvard.edu\/acts\/wp-json\/wp\/v2\/posts\/76\/revisions\/158"}],"wp:attachment":[{"href":"https:\/\/archive.blogs.harvard.edu\/acts\/wp-json\/wp\/v2\/media?parent=76"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/archive.blogs.harvard.edu\/acts\/wp-json\/wp\/v2\/categories?post=76"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/archive.blogs.harvard.edu\/acts\/wp-json\/wp\/v2\/tags?post=76"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}