{"action":"created","comment":{"url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls/comments/39583137","id":39583137,"diff_hunk":"@@ -74,7 +171,13 @@ implementation choices from users?\n \n **Response**\n \n+The best (and possibly only) reason to let the user know what the implementation details are is if it affects (especially restricts) the things the user is able to do, and the things the user **must** do in order to make their program run.  For example, in the choice between an interpreter and a compiler, there is a difference in what you're able to do at runtime, as well as the existence of a (potentially executable) generated file.  Additionally, performing things such as static analysis is generally easier when everything happens at compile time versus runtime.  \n+\n+In general, we should hide as much as possible - details about the internal parser or AST are almost certainly irrelevant to the end user, and would only confuse the user.  \"**Keep APIs free of implementations details.**\t They confuse users and inhibit the flexibility to evolve.\" [Bloch, 2006].  In general, any implementation choice that affects how it is run, written, or edited, should be revealed to the user to the extent they need it for their workflow.\n \n+However, there is a case that could be described as exposing implementation details. Sometimes we are tempted to hide implementation so much that we lose extensibility, and lock users into one workflow. For example, the CS5 sound lab tried to hide file operations except for reading in from an initial file. As a result, every function automatically wrote to a file and then played the result, because there was no easy way for the user to do those actions. Another related question is how much to allow interoperability between an internal DSL and the host language. Sometimes it is convenient to provide optional hooks into what could be considered implementation details.\n+\n+Therefore, implementation details should be hidden until the point that they limit extensibility. Those details that are exposed should be entirely optional, available to the advanced user who wants to extend functionality, but hidden from the novice.","path":"language-design.md","position":163,"original_position":163,"commit_id":"31265623da30f1a12f3093ba2089d3cf1d1d994b","original_commit_id":"31265623da30f1a12f3093ba2089d3cf1d1d994b","user":{"login":"Dannnno","id":6121935,"avatar_url":"https://avatars.githubusercontent.com/u/6121935?v=3","gravatar_id":"","url":"https://api.github.com/users/Dannnno","html_url":"https://github.com/Dannnno","followers_url":"https://api.github.com/users/Dannnno/followers","following_url":"https://api.github.com/users/Dannnno/following{/other_user}","gists_url":"https://api.github.com/users/Dannnno/gists{/gist_id}","starred_url":"https://api.github.com/users/Dannnno/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Dannnno/subscriptions","organizations_url":"https://api.github.com/users/Dannnno/orgs","repos_url":"https://api.github.com/users/Dannnno/repos","events_url":"https://api.github.com/users/Dannnno/events{/privacy}","received_events_url":"https://api.github.com/users/Dannnno/received_events","type":"User","site_admin":false},"body":"I think that's a good point.  Understanding how something works (for example, CPython's GIL) has a huge impact on your ability to improve (for example, get rid of the GIL) the language (as well as make use of it).\r\n\r\nThat being said, I think my example (the GIL) is a fundamentally flawed implementation detail that restricts or limits the user.","created_at":"2015-09-16T00:35:33Z","updated_at":"2015-09-16T00:35:33Z","html_url":"https://github.com/hmc-cs111-fall2015/language-design/pull/4#discussion_r39583137","pull_request_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls/4","_links":{"self":{"href":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls/comments/39583137"},"html":{"href":"https://github.com/hmc-cs111-fall2015/language-design/pull/4#discussion_r39583137"},"pull_request":{"href":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls/4"}}},"pull_request":{"url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls/4","id":44892359,"html_url":"https://github.com/hmc-cs111-fall2015/language-design/pull/4","diff_url":"https://github.com/hmc-cs111-fall2015/language-design/pull/4.diff","patch_url":"https://github.com/hmc-cs111-fall2015/language-design/pull/4.patch","issue_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/issues/4","number":4,"state":"open","locked":false,"title":"Matt and Dan's Submission","user":{"login":"MatthewValentine","id":2508029,"avatar_url":"https://avatars.githubusercontent.com/u/2508029?v=3","gravatar_id":"","url":"https://api.github.com/users/MatthewValentine","html_url":"https://github.com/MatthewValentine","followers_url":"https://api.github.com/users/MatthewValentine/followers","following_url":"https://api.github.com/users/MatthewValentine/following{/other_user}","gists_url":"https://api.github.com/users/MatthewValentine/gists{/gist_id}","starred_url":"https://api.github.com/users/MatthewValentine/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MatthewValentine/subscriptions","organizations_url":"https://api.github.com/users/MatthewValentine/orgs","repos_url":"https://api.github.com/users/MatthewValentine/repos","events_url":"https://api.github.com/users/MatthewValentine/events{/privacy}","received_events_url":"https://api.github.com/users/MatthewValentine/received_events","type":"User","site_admin":false},"body":"","created_at":"2015-09-14T04:35:26Z","updated_at":"2015-09-16T00:35:33Z","closed_at":null,"merged_at":null,"merge_commit_sha":"96d4a2c6815b71a9e44028f36d502b0a504c1a78","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls/4/commits","review_comments_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls/4/comments","review_comment_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls/comments{/number}","comments_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/issues/4/comments","statuses_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/statuses/31265623da30f1a12f3093ba2089d3cf1d1d994b","head":{"label":"MatthewValentine:master","ref":"master","sha":"31265623da30f1a12f3093ba2089d3cf1d1d994b","user":{"login":"MatthewValentine","id":2508029,"avatar_url":"https://avatars.githubusercontent.com/u/2508029?v=3","gravatar_id":"","url":"https://api.github.com/users/MatthewValentine","html_url":"https://github.com/MatthewValentine","followers_url":"https://api.github.com/users/MatthewValentine/followers","following_url":"https://api.github.com/users/MatthewValentine/following{/other_user}","gists_url":"https://api.github.com/users/MatthewValentine/gists{/gist_id}","starred_url":"https://api.github.com/users/MatthewValentine/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MatthewValentine/subscriptions","organizations_url":"https://api.github.com/users/MatthewValentine/orgs","repos_url":"https://api.github.com/users/MatthewValentine/repos","events_url":"https://api.github.com/users/MatthewValentine/events{/privacy}","received_events_url":"https://api.github.com/users/MatthewValentine/received_events","type":"User","site_admin":false},"repo":{"id":42381519,"name":"language-design","full_name":"MatthewValentine/language-design","owner":{"login":"MatthewValentine","id":2508029,"avatar_url":"https://avatars.githubusercontent.com/u/2508029?v=3","gravatar_id":"","url":"https://api.github.com/users/MatthewValentine","html_url":"https://github.com/MatthewValentine","followers_url":"https://api.github.com/users/MatthewValentine/followers","following_url":"https://api.github.com/users/MatthewValentine/following{/other_user}","gists_url":"https://api.github.com/users/MatthewValentine/gists{/gist_id}","starred_url":"https://api.github.com/users/MatthewValentine/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MatthewValentine/subscriptions","organizations_url":"https://api.github.com/users/MatthewValentine/orgs","repos_url":"https://api.github.com/users/MatthewValentine/repos","events_url":"https://api.github.com/users/MatthewValentine/events{/privacy}","received_events_url":"https://api.github.com/users/MatthewValentine/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/MatthewValentine/language-design","description":"","fork":true,"url":"https://api.github.com/repos/MatthewValentine/language-design","forks_url":"https://api.github.com/repos/MatthewValentine/language-design/forks","keys_url":"https://api.github.com/repos/MatthewValentine/language-design/keys{/key_id}","collaborators_url":"https://api.github.com/repos/MatthewValentine/language-design/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/MatthewValentine/language-design/teams","hooks_url":"https://api.github.com/repos/MatthewValentine/language-design/hooks","issue_events_url":"https://api.github.com/repos/MatthewValentine/language-design/issues/events{/number}","events_url":"https://api.github.com/repos/MatthewValentine/language-design/events","assignees_url":"https://api.github.com/repos/MatthewValentine/language-design/assignees{/user}","branches_url":"https://api.github.com/repos/MatthewValentine/language-design/branches{/branch}","tags_url":"https://api.github.com/repos/MatthewValentine/language-design/tags","blobs_url":"https://api.github.com/repos/MatthewValentine/language-design/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/MatthewValentine/language-design/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/MatthewValentine/language-design/git/refs{/sha}","trees_url":"https://api.github.com/repos/MatthewValentine/language-design/git/trees{/sha}","statuses_url":"https://api.github.com/repos/MatthewValentine/language-design/statuses/{sha}","languages_url":"https://api.github.com/repos/MatthewValentine/language-design/languages","stargazers_url":"https://api.github.com/repos/MatthewValentine/language-design/stargazers","contributors_url":"https://api.github.com/repos/MatthewValentine/language-design/contributors","subscribers_url":"https://api.github.com/repos/MatthewValentine/language-design/subscribers","subscription_url":"https://api.github.com/repos/MatthewValentine/language-design/subscription","commits_url":"https://api.github.com/repos/MatthewValentine/language-design/commits{/sha}","git_commits_url":"https://api.github.com/repos/MatthewValentine/language-design/git/commits{/sha}","comments_url":"https://api.github.com/repos/MatthewValentine/language-design/comments{/number}","issue_comment_url":"https://api.github.com/repos/MatthewValentine/language-design/issues/comments{/number}","contents_url":"https://api.github.com/repos/MatthewValentine/language-design/contents/{+path}","compare_url":"https://api.github.com/repos/MatthewValentine/language-design/compare/{base}...{head}","merges_url":"https://api.github.com/repos/MatthewValentine/language-design/merges","archive_url":"https://api.github.com/repos/MatthewValentine/language-design/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/MatthewValentine/language-design/downloads","issues_url":"https://api.github.com/repos/MatthewValentine/language-design/issues{/number}","pulls_url":"https://api.github.com/repos/MatthewValentine/language-design/pulls{/number}","milestones_url":"https://api.github.com/repos/MatthewValentine/language-design/milestones{/number}","notifications_url":"https://api.github.com/repos/MatthewValentine/language-design/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/MatthewValentine/language-design/labels{/name}","releases_url":"https://api.github.com/repos/MatthewValentine/language-design/releases{/id}","created_at":"2015-09-13T02:55:40Z","updated_at":"2015-09-10T00:37:04Z","pushed_at":"2015-09-14T04:33:36Z","git_url":"git://github.com/MatthewValentine/language-design.git","ssh_url":"git@github.com:MatthewValentine/language-design.git","clone_url":"https://github.com/MatthewValentine/language-design.git","svn_url":"https://github.com/MatthewValentine/language-design","homepage":null,"size":123,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1,"mirror_url":null,"open_issues_count":0,"forks":1,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"hmc-cs111-fall2015:master","ref":"master","sha":"4224a70776df313dc70c08c0b9e8b27d89a664e6","user":{"login":"hmc-cs111-fall2015","id":12563789,"avatar_url":"https://avatars.githubusercontent.com/u/12563789?v=3","gravatar_id":"","url":"https://api.github.com/users/hmc-cs111-fall2015","html_url":"https://github.com/hmc-cs111-fall2015","followers_url":"https://api.github.com/users/hmc-cs111-fall2015/followers","following_url":"https://api.github.com/users/hmc-cs111-fall2015/following{/other_user}","gists_url":"https://api.github.com/users/hmc-cs111-fall2015/gists{/gist_id}","starred_url":"https://api.github.com/users/hmc-cs111-fall2015/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hmc-cs111-fall2015/subscriptions","organizations_url":"https://api.github.com/users/hmc-cs111-fall2015/orgs","repos_url":"https://api.github.com/users/hmc-cs111-fall2015/repos","events_url":"https://api.github.com/users/hmc-cs111-fall2015/events{/privacy}","received_events_url":"https://api.github.com/users/hmc-cs111-fall2015/received_events","type":"Organization","site_admin":false},"repo":{"id":42158427,"name":"language-design","full_name":"hmc-cs111-fall2015/language-design","owner":{"login":"hmc-cs111-fall2015","id":12563789,"avatar_url":"https://avatars.githubusercontent.com/u/12563789?v=3","gravatar_id":"","url":"https://api.github.com/users/hmc-cs111-fall2015","html_url":"https://github.com/hmc-cs111-fall2015","followers_url":"https://api.github.com/users/hmc-cs111-fall2015/followers","following_url":"https://api.github.com/users/hmc-cs111-fall2015/following{/other_user}","gists_url":"https://api.github.com/users/hmc-cs111-fall2015/gists{/gist_id}","starred_url":"https://api.github.com/users/hmc-cs111-fall2015/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hmc-cs111-fall2015/subscriptions","organizations_url":"https://api.github.com/users/hmc-cs111-fall2015/orgs","repos_url":"https://api.github.com/users/hmc-cs111-fall2015/repos","events_url":"https://api.github.com/users/hmc-cs111-fall2015/events{/privacy}","received_events_url":"https://api.github.com/users/hmc-cs111-fall2015/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/hmc-cs111-fall2015/language-design","description":"","fork":false,"url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design","forks_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/forks","keys_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/keys{/key_id}","collaborators_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/teams","hooks_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/hooks","issue_events_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/issues/events{/number}","events_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/events","assignees_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/assignees{/user}","branches_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/branches{/branch}","tags_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/tags","blobs_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/git/refs{/sha}","trees_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/git/trees{/sha}","statuses_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/statuses/{sha}","languages_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/languages","stargazers_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/stargazers","contributors_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/contributors","subscribers_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/subscribers","subscription_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/subscription","commits_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/commits{/sha}","git_commits_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/git/commits{/sha}","comments_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/comments{/number}","issue_comment_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/issues/comments{/number}","contents_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/contents/{+path}","compare_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/compare/{base}...{head}","merges_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/merges","archive_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/downloads","issues_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/issues{/number}","pulls_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls{/number}","milestones_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/milestones{/number}","notifications_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/labels{/name}","releases_url":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/releases{/id}","created_at":"2015-09-09T05:41:09Z","updated_at":"2015-09-10T00:37:04Z","pushed_at":"2015-09-14T07:00:50Z","git_url":"git://github.com/hmc-cs111-fall2015/language-design.git","ssh_url":"git@github.com:hmc-cs111-fall2015/language-design.git","clone_url":"https://github.com/hmc-cs111-fall2015/language-design.git","svn_url":"https://github.com/hmc-cs111-fall2015/language-design","homepage":null,"size":534,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":7,"mirror_url":null,"open_issues_count":6,"forks":7,"open_issues":6,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls/4"},"html":{"href":"https://github.com/hmc-cs111-fall2015/language-design/pull/4"},"issue":{"href":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/issues/4"},"comments":{"href":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/issues/4/comments"},"review_comments":{"href":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls/4/comments"},"review_comment":{"href":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/pulls/4/commits"},"statuses":{"href":"https://api.github.com/repos/hmc-cs111-fall2015/language-design/statuses/31265623da30f1a12f3093ba2089d3cf1d1d994b"}}}}