{"action":"created","comment":{"url":"https://api.github.com/repos/angular/material2/pulls/comments/50470341","id":50470341,"diff_hunk":"@@ -0,0 +1,139 @@\n+# Angular Material Coding Standards\n+\n+\n+## Code style\n+\n+The [Google JavaScript Style Guide](https://google.github.io/styleguide/javascriptguide.xml) is the\n+basis for our coding style, with additional guidance here where that style guide is not aligned with\n+ES6 or TypeScript.\n+\n+## Coding practices\n+\n+### General\n+\n+#### Write useful comments\n+Comments that explain what some block of code does are nice; they can tell you something in less time than it would take to follow through the code itself.\n+\n+Comments that explain why some block of code exists at all, or does something the way it does, \n+are invaluable. The \"why\" is difficult, or sometimes impossible, to track down without seeking out \n+the original author. When collaborators are in the same room, this hurts productivity. \n+When collaborators are in different timezones, this can be devastating to productivity.\n+\n+For example, this is a not-very-useful comment:\n+```ts\n+// Set default tabindex.\n+if (!$attrs['tabindex']) {\n+  $element.attr('tabindex', '-1');\n+}\n+```\n+\n+While this is much more useful:\n+```ts\n+// Unless the user specifies so, the calendar should not be a tab stop.\n+// This is necessary because ngAria might add a tabindex to anything with an ng-model\n+// (based on whether or not the user has turned that particular feature on/off).\n+if (!$attrs['tabindex']) {\n+  $element.attr('tabindex', '-1');\n+}\n+```\n+\n+#### Prefer more focused, granular components vs. complex, configurable components.\n+\n+For example, rather than doing this:\n+```ts\n+<md-button>Basic button</md-button>\n+<md-button class=\"md-fab\">FAB</md-button>\n+<md-button class=\"md-icon-button\">pony</md-button>\n+```\n+\n+do this:\n+```ts\n+<md-button>Basic button</md-button>\n+<md-fab>FAB</md-fab>\n+<md-icon-button>pony</md-icon-button>\n+```\n+\n+#### Prefer small, focused modules\n+Keeping modules to a single responsibility makes the code easier to test, consume, and maintain. \n+ES6 modules offer a straightforward way to organize code into logical, granular units. \n+Ideally, individual files are 200 - 300 lines of code.\n+\n+#### Less is more\n+Once a feature is released, it never goes away. We should avoid adding features that don't offer \n+high user value for price we pay both in maintenance, complexity, and payload size. When in doubt, \n+leave it out. \n+\n+This applies especially so to providing two different APIs to accomplish the same thing. Always \n+prefer sticking to a _single_ API for accomplishing something. \n+\n+### TypeScript\n+\n+#### Provide function descriptions\n+For functions that are more complicated than a simple getter/setter, provide at least a brief \n+sentence explaining what the function does and/or _why_ it does something.\n+\n+### CSS\n+\n+#### Be cautious with use of `display: flex`\n+* The [baseline calculation for flex elements](http://www.w3.org/TR/css-flexbox-1/#flex-baselines) \n+is different than other display values, making it difficult to align flex elements with standard \n+elements like input and button.\n+* Component outermost elements are never flex (block or inline-block)\n+* Don't use `display: flex` on elements that will contain projected content.\n+\n+#### Use lowest specificity possible\n+Always prioritize lower specificity over other factors. Most style definitions should consist of a \n+single element or css selector plus necessary state modifiers. Avoid SCSS nesting for the sake of \n+code organization. This will allow users to much more easily override styles.\n+\n+For example, rather than doing this:\n+```scss\n+md-calendar {\n+  display: block;\n+\n+  .md-month {\n+    display: inline-block;\n+\n+    .md-date.md-selected {\n+      font-weight: bold;\n+    }\n+  }\n+}\n+```\n+\n+do this:\n+```scss\n+md-calendar {\n+  display: block;\n+}\n+\n+.md-calendar-month {\n+  display: inline-block;\n+}\n+\n+.md-calendar-date.md-selected {\n+  font-weight: bold;\n+}\n+```\n+\n+#### Never set a margin on a host element.\n+The end-user of a component should be the one to decide how much margin a component has around it.","path":"CODING_STANDARDS.md","position":120,"original_position":120,"commit_id":"f6480ce21f852bcd57be890af6c6c113a038aeab","original_commit_id":"8e1530cf1bcf2aab644eb074a7c8a5f5b51518a7","user":{"login":"robertmesserle","id":571363,"avatar_url":"https://avatars.githubusercontent.com/u/571363?v=3","gravatar_id":"","url":"https://api.github.com/users/robertmesserle","html_url":"https://github.com/robertmesserle","followers_url":"https://api.github.com/users/robertmesserle/followers","following_url":"https://api.github.com/users/robertmesserle/following{/other_user}","gists_url":"https://api.github.com/users/robertmesserle/gists{/gist_id}","starred_url":"https://api.github.com/users/robertmesserle/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/robertmesserle/subscriptions","organizations_url":"https://api.github.com/users/robertmesserle/orgs","repos_url":"https://api.github.com/users/robertmesserle/repos","events_url":"https://api.github.com/users/robertmesserle/events{/privacy}","received_events_url":"https://api.github.com/users/robertmesserle/received_events","type":"User","site_admin":false},"body":"More details on this method here: https://css-tricks.com/snippets/css/clear-fix/","created_at":"2016-01-21T21:54:11Z","updated_at":"2016-01-21T21:54:11Z","html_url":"https://github.com/angular/material2/pull/26#discussion_r50470341","pull_request_url":"https://api.github.com/repos/angular/material2/pulls/26","_links":{"self":{"href":"https://api.github.com/repos/angular/material2/pulls/comments/50470341"},"html":{"href":"https://github.com/angular/material2/pull/26#discussion_r50470341"},"pull_request":{"href":"https://api.github.com/repos/angular/material2/pulls/26"}}},"pull_request":{"url":"https://api.github.com/repos/angular/material2/pulls/26","id":56693470,"html_url":"https://github.com/angular/material2/pull/26","diff_url":"https://github.com/angular/material2/pull/26.diff","patch_url":"https://github.com/angular/material2/pull/26.patch","issue_url":"https://api.github.com/repos/angular/material2/issues/26","number":26,"state":"open","locked":false,"title":"docs(): add coding standards doc","user":{"login":"jelbourn","id":838736,"avatar_url":"https://avatars.githubusercontent.com/u/838736?v=3","gravatar_id":"","url":"https://api.github.com/users/jelbourn","html_url":"https://github.com/jelbourn","followers_url":"https://api.github.com/users/jelbourn/followers","following_url":"https://api.github.com/users/jelbourn/following{/other_user}","gists_url":"https://api.github.com/users/jelbourn/gists{/gist_id}","starred_url":"https://api.github.com/users/jelbourn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jelbourn/subscriptions","organizations_url":"https://api.github.com/users/jelbourn/orgs","repos_url":"https://api.github.com/users/jelbourn/repos","events_url":"https://api.github.com/users/jelbourn/events{/privacy}","received_events_url":"https://api.github.com/users/jelbourn/received_events","type":"User","site_admin":false},"body":"R: @robertmesserle @hansl @kara \r\n\r\nLet me know if there's anything we should change or add.","created_at":"2016-01-21T01:28:35Z","updated_at":"2016-01-21T21:54:11Z","closed_at":null,"merged_at":null,"merge_commit_sha":"6d1c93761e56dccd6e7637b8d0341cb8ed119272","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/angular/material2/pulls/26/commits","review_comments_url":"https://api.github.com/repos/angular/material2/pulls/26/comments","review_comment_url":"https://api.github.com/repos/angular/material2/pulls/comments{/number}","comments_url":"https://api.github.com/repos/angular/material2/issues/26/comments","statuses_url":"https://api.github.com/repos/angular/material2/statuses/f6480ce21f852bcd57be890af6c6c113a038aeab","head":{"label":"jelbourn:code-standards","ref":"code-standards","sha":"f6480ce21f852bcd57be890af6c6c113a038aeab","user":{"login":"jelbourn","id":838736,"avatar_url":"https://avatars.githubusercontent.com/u/838736?v=3","gravatar_id":"","url":"https://api.github.com/users/jelbourn","html_url":"https://github.com/jelbourn","followers_url":"https://api.github.com/users/jelbourn/followers","following_url":"https://api.github.com/users/jelbourn/following{/other_user}","gists_url":"https://api.github.com/users/jelbourn/gists{/gist_id}","starred_url":"https://api.github.com/users/jelbourn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jelbourn/subscriptions","organizations_url":"https://api.github.com/users/jelbourn/orgs","repos_url":"https://api.github.com/users/jelbourn/repos","events_url":"https://api.github.com/users/jelbourn/events{/privacy}","received_events_url":"https://api.github.com/users/jelbourn/received_events","type":"User","site_admin":false},"repo":{"id":49016875,"name":"material2","full_name":"jelbourn/material2","owner":{"login":"jelbourn","id":838736,"avatar_url":"https://avatars.githubusercontent.com/u/838736?v=3","gravatar_id":"","url":"https://api.github.com/users/jelbourn","html_url":"https://github.com/jelbourn","followers_url":"https://api.github.com/users/jelbourn/followers","following_url":"https://api.github.com/users/jelbourn/following{/other_user}","gists_url":"https://api.github.com/users/jelbourn/gists{/gist_id}","starred_url":"https://api.github.com/users/jelbourn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jelbourn/subscriptions","organizations_url":"https://api.github.com/users/jelbourn/orgs","repos_url":"https://api.github.com/users/jelbourn/repos","events_url":"https://api.github.com/users/jelbourn/events{/privacy}","received_events_url":"https://api.github.com/users/jelbourn/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/jelbourn/material2","description":"","fork":true,"url":"https://api.github.com/repos/jelbourn/material2","forks_url":"https://api.github.com/repos/jelbourn/material2/forks","keys_url":"https://api.github.com/repos/jelbourn/material2/keys{/key_id}","collaborators_url":"https://api.github.com/repos/jelbourn/material2/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/jelbourn/material2/teams","hooks_url":"https://api.github.com/repos/jelbourn/material2/hooks","issue_events_url":"https://api.github.com/repos/jelbourn/material2/issues/events{/number}","events_url":"https://api.github.com/repos/jelbourn/material2/events","assignees_url":"https://api.github.com/repos/jelbourn/material2/assignees{/user}","branches_url":"https://api.github.com/repos/jelbourn/material2/branches{/branch}","tags_url":"https://api.github.com/repos/jelbourn/material2/tags","blobs_url":"https://api.github.com/repos/jelbourn/material2/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/jelbourn/material2/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/jelbourn/material2/git/refs{/sha}","trees_url":"https://api.github.com/repos/jelbourn/material2/git/trees{/sha}","statuses_url":"https://api.github.com/repos/jelbourn/material2/statuses/{sha}","languages_url":"https://api.github.com/repos/jelbourn/material2/languages","stargazers_url":"https://api.github.com/repos/jelbourn/material2/stargazers","contributors_url":"https://api.github.com/repos/jelbourn/material2/contributors","subscribers_url":"https://api.github.com/repos/jelbourn/material2/subscribers","subscription_url":"https://api.github.com/repos/jelbourn/material2/subscription","commits_url":"https://api.github.com/repos/jelbourn/material2/commits{/sha}","git_commits_url":"https://api.github.com/repos/jelbourn/material2/git/commits{/sha}","comments_url":"https://api.github.com/repos/jelbourn/material2/comments{/number}","issue_comment_url":"https://api.github.com/repos/jelbourn/material2/issues/comments{/number}","contents_url":"https://api.github.com/repos/jelbourn/material2/contents/{+path}","compare_url":"https://api.github.com/repos/jelbourn/material2/compare/{base}...{head}","merges_url":"https://api.github.com/repos/jelbourn/material2/merges","archive_url":"https://api.github.com/repos/jelbourn/material2/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/jelbourn/material2/downloads","issues_url":"https://api.github.com/repos/jelbourn/material2/issues{/number}","pulls_url":"https://api.github.com/repos/jelbourn/material2/pulls{/number}","milestones_url":"https://api.github.com/repos/jelbourn/material2/milestones{/number}","notifications_url":"https://api.github.com/repos/jelbourn/material2/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/jelbourn/material2/labels{/name}","releases_url":"https://api.github.com/repos/jelbourn/material2/releases{/id}","created_at":"2016-01-04T19:01:46Z","updated_at":"2016-01-04T18:52:25Z","pushed_at":"2016-01-21T21:27:46Z","git_url":"git://github.com/jelbourn/material2.git","ssh_url":"git@github.com:jelbourn/material2.git","clone_url":"https://github.com/jelbourn/material2.git","svn_url":"https://github.com/jelbourn/material2","homepage":null,"size":59,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"angular:master","ref":"master","sha":"9dcb2bc50f4b74ce95db438a8ccfbe19e3ed831e","user":{"login":"angular","id":139426,"avatar_url":"https://avatars.githubusercontent.com/u/139426?v=3","gravatar_id":"","url":"https://api.github.com/users/angular","html_url":"https://github.com/angular","followers_url":"https://api.github.com/users/angular/followers","following_url":"https://api.github.com/users/angular/following{/other_user}","gists_url":"https://api.github.com/users/angular/gists{/gist_id}","starred_url":"https://api.github.com/users/angular/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/angular/subscriptions","organizations_url":"https://api.github.com/users/angular/orgs","repos_url":"https://api.github.com/users/angular/repos","events_url":"https://api.github.com/users/angular/events{/privacy}","received_events_url":"https://api.github.com/users/angular/received_events","type":"Organization","site_admin":false},"repo":{"id":49016322,"name":"material2","full_name":"angular/material2","owner":{"login":"angular","id":139426,"avatar_url":"https://avatars.githubusercontent.com/u/139426?v=3","gravatar_id":"","url":"https://api.github.com/users/angular","html_url":"https://github.com/angular","followers_url":"https://api.github.com/users/angular/followers","following_url":"https://api.github.com/users/angular/following{/other_user}","gists_url":"https://api.github.com/users/angular/gists{/gist_id}","starred_url":"https://api.github.com/users/angular/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/angular/subscriptions","organizations_url":"https://api.github.com/users/angular/orgs","repos_url":"https://api.github.com/users/angular/repos","events_url":"https://api.github.com/users/angular/events{/privacy}","received_events_url":"https://api.github.com/users/angular/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/angular/material2","description":"Material Design components for Angular 2","fork":false,"url":"https://api.github.com/repos/angular/material2","forks_url":"https://api.github.com/repos/angular/material2/forks","keys_url":"https://api.github.com/repos/angular/material2/keys{/key_id}","collaborators_url":"https://api.github.com/repos/angular/material2/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/angular/material2/teams","hooks_url":"https://api.github.com/repos/angular/material2/hooks","issue_events_url":"https://api.github.com/repos/angular/material2/issues/events{/number}","events_url":"https://api.github.com/repos/angular/material2/events","assignees_url":"https://api.github.com/repos/angular/material2/assignees{/user}","branches_url":"https://api.github.com/repos/angular/material2/branches{/branch}","tags_url":"https://api.github.com/repos/angular/material2/tags","blobs_url":"https://api.github.com/repos/angular/material2/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/angular/material2/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/angular/material2/git/refs{/sha}","trees_url":"https://api.github.com/repos/angular/material2/git/trees{/sha}","statuses_url":"https://api.github.com/repos/angular/material2/statuses/{sha}","languages_url":"https://api.github.com/repos/angular/material2/languages","stargazers_url":"https://api.github.com/repos/angular/material2/stargazers","contributors_url":"https://api.github.com/repos/angular/material2/contributors","subscribers_url":"https://api.github.com/repos/angular/material2/subscribers","subscription_url":"https://api.github.com/repos/angular/material2/subscription","commits_url":"https://api.github.com/repos/angular/material2/commits{/sha}","git_commits_url":"https://api.github.com/repos/angular/material2/git/commits{/sha}","comments_url":"https://api.github.com/repos/angular/material2/comments{/number}","issue_comment_url":"https://api.github.com/repos/angular/material2/issues/comments{/number}","contents_url":"https://api.github.com/repos/angular/material2/contents/{+path}","compare_url":"https://api.github.com/repos/angular/material2/compare/{base}...{head}","merges_url":"https://api.github.com/repos/angular/material2/merges","archive_url":"https://api.github.com/repos/angular/material2/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/angular/material2/downloads","issues_url":"https://api.github.com/repos/angular/material2/issues{/number}","pulls_url":"https://api.github.com/repos/angular/material2/pulls{/number}","milestones_url":"https://api.github.com/repos/angular/material2/milestones{/number}","notifications_url":"https://api.github.com/repos/angular/material2/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/angular/material2/labels{/name}","releases_url":"https://api.github.com/repos/angular/material2/releases{/id}","created_at":"2016-01-04T18:50:02Z","updated_at":"2016-01-21T21:23:24Z","pushed_at":"2016-01-21T21:43:35Z","git_url":"git://github.com/angular/material2.git","ssh_url":"git@github.com:angular/material2.git","clone_url":"https://github.com/angular/material2.git","svn_url":"https://github.com/angular/material2","homepage":"","size":81,"stargazers_count":256,"watchers_count":256,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":26,"mirror_url":null,"open_issues_count":4,"forks":26,"open_issues":4,"watchers":256,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/angular/material2/pulls/26"},"html":{"href":"https://github.com/angular/material2/pull/26"},"issue":{"href":"https://api.github.com/repos/angular/material2/issues/26"},"comments":{"href":"https://api.github.com/repos/angular/material2/issues/26/comments"},"review_comments":{"href":"https://api.github.com/repos/angular/material2/pulls/26/comments"},"review_comment":{"href":"https://api.github.com/repos/angular/material2/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/angular/material2/pulls/26/commits"},"statuses":{"href":"https://api.github.com/repos/angular/material2/statuses/f6480ce21f852bcd57be890af6c6c113a038aeab"}}}}