GitHub PullRequestReviewCommentEvent at 2014-05-27 21:13:08
Repository: developer.rackspace.com
Actor: smashwilson
Payload: {"comment":{"url":"https://api.github.com/repos/rackerlabs/developer.rackspace.com/pulls/comments/13102854","id":13102854,"diff_hunk":"@@ -21,39 +21,70 @@ Code blocks go in this order::\n \n   .. code-block:: sh\n \n+If there's a new language you want to add code samples for, insert it where it fits alphabetically.\n \n-If there's a new language you want to add code samples for, insert it where it fits alphabetically. \n+If starting a new narrative/code section, be sure to add all the code block sections to each `.rst` you create, to help ``git`` merge them later. You can copy and paste the section above into each sample file.\n \n-\n-If starting a new narrative/code section, be sure to add all the code block sections to each `.rst` you create for PR sanity.\n+Language\n+--------\n \n Use neutral language instead of gerunds:\n \n * **GOOD**: Set up your xxxx.\n * **BAD**: Setting up your xxxx.\n \n-Use comments in code samples when each sample comprises multiple steps.\n+Use comments in code samples when each sample comprises multiple steps, to clarify the use of parameters that aren't obvious by name, or whenever something in your SDK behaves differently than the others.\n+\n+Use TODO comments in code samples instead of printing out strings or handling errors.\n+\n+Limit lines in sample files to 120 characters.\n+\n+Placeholders\n+------------\n \n-Use TODO in code samples instead of printing out strings.\n+When using a value the developer needs to insert by referencing some out-of-band information, use a ``{placeholder}``.\n \n-Limit lines to 120 characters.\n+Our convention is to name these in lowercase with camelCasing, regardless of the underlying language idioms. Consistency among samples is important for us to be able to automate later with a simple find-and-replace. Also, we *want* them to stand out, so it's obvious at a glance that a user needs to replace them with a real value.\n \n-When using a value the developer needs to input, surround the value in curly brackets. The convention is to name them as lowercased with camelCasing.\n-Here are some that should be consistent in the different language examples:\n+Don't use ``{placeholders}`` for every parameter! A good rule of thumb is to use a ``{placeholder}`` if the developer is going to need to look something up elsewhere, like the web UI, to find a correct value. Authentication credentials, addresses, or UUIDs are good examples of appropriate ``{placeholder}`` usage.","path":"src/docs/CONTRIBUTING.rst","position":37,"original_position":37,"commit_id":"6c2061db3e0c36aadd24ab611b9d135724de36eb","original_commit_id":"6c2061db3e0c36aadd24ab611b9d135724de36eb","user":{"login":"smashwilson","id":17565,"avatar_url":"https://avatars.githubusercontent.com/u/17565?","gravatar_id":"9c5da6e05ae65fbd295344270feba072","url":"https://api.github.com/users/smashwilson","html_url":"https://github.com/smashwilson","followers_url":"https://api.github.com/users/smashwilson/followers","following_url":"https://api.github.com/users/smashwilson/following{/other_user}","gists_url":"https://api.github.com/users/smashwilson/gists{/gist_id}","starred_url":"https://api.github.com/users/smashwilson/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/smashwilson/subscriptions","organizations_url":"https://api.github.com/users/smashwilson/orgs","repos_url":"https://api.github.com/users/smashwilson/repos","events_url":"https://api.github.com/users/smashwilson/events{/privacy}","received_events_url":"https://api.github.com/users/smashwilson/received_events","type":"User","site_admin":false},"body":"I'm using \"placeholder\" here in the specific sense as *those curly-braced things like \"{apiKey}\"*. I'm arguing against using them absolutely everywhere because:\r\n\r\n * They're visually jarring. In most languages, they don't match the idiomatic naming conventions, and in some places (like JSON payloads, as you noted) they can even visually conflict with local syntax. There's no syntax that *wouldn't* be visually jarring across all samples.\r\n\r\n * They conceal parameter type information. You can use `\"{string}\"` to denote a String, sure, but what about integers, floats, dictionaries, UUIDs? The SDKs mostly use integers and strings, but a beginner doesn't know that.\r\n\r\n * They unnecessarily inhibit copy-and-pasteability for simple things. In places like \"creating a server\" or \"upload a file\", it doesn't matter if every new customer's first server is called \"my_awesome_server\" or whatever. What matters is how much time elapsed between \"I want to know how to do this\" and being able to make it happen.\r\n\r\nI've got a few alternatives listed after.\r\n\r\n> Remember that the getting started guides have googleable permalinks to every subsection so relying on a value that was somehow defined earlier in the guide is not a good assumption.\r\n\r\nThat's actually why I later recommend introducing a subtle way to distinguish between variables that persist throughout the narrative and those that are \"local\". In Ruby I've tried to use `@instance_variables` for persistent ones and `temporary_variables` for local ones, for example.\r\n\r\nIf a reader doesn't know what `@image.id` is yet, they're also not going to know what `{imageId}` is. The difference is that the former leads naturally to *ctrl-f @image* and scrolling up to its first occurrence in the narrative, and ties explicitly back to the older concept.\r\n\r\n> a placeholder (the same placeholder)\r\n\r\nConsistency is a big thing, yes: farther down I'm advocating for using similar variable names and literal values across samples for that exact reason.","created_at":"2014-05-27T21:13:08Z","updated_at":"2014-05-27T21:13:08Z","html_url":"https://github.com/rackerlabs/developer.rackspace.com/pull/200#discussion_r13102854","pull_request_url":"https://api.github.com/repos/rackerlabs/developer.rackspace.com/pulls/200","_links":{"self":{"href":"https://api.github.com/repos/rackerlabs/developer.rackspace.com/pulls/comments/13102854"},"html":{"href":"https://github.com/rackerlabs/developer.rackspace.com/pull/200#discussion_r13102854"},"pull_request":{"href":"https://api.github.com/repos/rackerlabs/developer.rackspace.com/pulls/200"}}}}