-
Notifications
You must be signed in to change notification settings - Fork 122
Style Guide
The general rule of indefinite articles that most people think of is that "a" is used before words beginning with consonants and "an" is used before words beginning with vowels.
Examples: a computer, a framework, a network
Examples: an application, an email, an index
However, it's important to pay attention to the sound of the word, because what the word sounds like — and not how it's spelled — is what determines the preceding article. If the first letter makes a consonant-like sound, then use "a." If the first letter makes a vowel-like sound, then use "an."
Examples: a unit, a user
Examples: an iCloud Core Data app, an NSMutableArray, an RSS reader
Avoid using abbreviations whenever possible unless they are well-known (e.g., i.e., etc.).
Designate acronyms by first spelling out the entire name and then placing the acronym immediately after in parentheses. On future references, refer to the acronym instead of the complete name unless it does not make sense.
Use American spelling, not British. When in doubt, look up a word in a dictionary for the proper usage. http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences
Spell out “and” in lieu of &. You may use the ampersand if it is part of the stylized name of onscreen elements, document titles, etc.
When using a colon in a normal sentence (i.e. not introducing something, as outlined above), do not capitalize the first word after the colon unless it is either a proper noun or it begins a complete sentence.
Example: Using UIView or CAAnimation animations has two big problems when it comes to interactive animations: The animations separate what you see on the screen from what the actual spacial properties are on the layer, and they directly manipulate the spacial properties.
Example: Using UIView or CAAnimation animations has two big problems when it comes to interactive animations: separating what you see on the screen from what the actual spacial properties are on the layer, and directly manipulating the spacial properties.
When introducing a long quote or lines of code, it’s important to use a colon after the introduction and before the quote or code, in order to specify its importance or that your reader should pay attention to the example.
Example: Using keyframe animations, this could look a little like so:
For the sake of consistency, do this whenever you are providing an example and have a line break between the introduction and example.
To Do
FANBOYS is used to remember the seven coordinating conjunctions: for, and, nor, but, or, yet, so. A coordinating conjunction joins together two independent clauses and should be preceded by a comma.
Example: We initialize the object with a table view, and the initializer looks like this:
Note that these words don’t need a comma before them every time; this is only necessary when joining together two independent clauses. There are other times this also occurs, but the rules vary depending on the grammar.
Use a comma before the coordinating conjunction in a list of three or more items.
Example: Objc.io is run by Chris, Daniel, and Florian.
This style is only used in American English and it is not required to always be used, but for the sake of consistency and clarity, we will use it all the time.
Compound adjectives are when two adjectives (or more) work in conjunction to describe a noun that they are preceding.
Example: With cloud-based sync, there was no longer a need to be at home in the vicinity of your computer to sync.
Note how it’s “cloud-based sync.” This is because both adjectives work together to describe the noun. You can’t say it’s “cloud sync” or “based sync,” because the adjectives don’t function properly alone. So to indicate that they are part of a pair, the hyphen is used to join them together.
Sometimes it’s clear when a compound adjective is needed (e.g. “peer-to-peer network”) but not always. When in doubt, ask if you can insert an “and” between the adjectives. If the answer is yes, it’s not a compound adjective. If the answer is no, then you need hyphens to indicate it’s a compound adjective.
Note that when a term that functions like this before a noun is placed after the noun, the compound adjective rule is no longer valid.
Example: The server made in-memory changes.
Example: The changes made by the server were in memory.
Be sure to avoid doing this with adverbs, aka words ending in “ly” (this is used in British English but not American English).
Use contractions when it makes sense and to improve readability (spelling everything out is often more formal and doesn't flow as well, but sometimes it's necessary for emphasis or wording to avoid the contraction).
Be sure not to make up contractions. Words such as “there’re” (short for there are) and “here’re” (short for here are) do not exist. If you are uncertain of the contraction form, here is a helpful list: http://grammar.about.com/od/words/a/EnglishContractions.htm
An em dash is so named because it takes up the same space as the lowercase letter m.
Use an em dash to take the place of other punctuation that would somehow emphasize or explain an idea, interrupt the flow of the sentence while still being on topic, or indicate a shift in ideas/direction.
Generally speaking, an em dash should not include any breaks, but this is optional if it improves readability by including breaks. As such, for objc.io, we choose to have a space between the dash on either end and the words surrounding it.
Example: The synchronous solutions discussed above are bespoke — you have to write lots of custom code for each app.
An en dash is so named because it takes up the same space as the lowercase letter n.
En dashes are rarely used for this publication. An example would be for when you are designating a time period (e.g. between a span of given months or years) but it is generally not necessary. In most cases, such as joining words together, you will be using the hyphen (see Compound Adjectives for more on this).
Format dates by listing the day, the month spelled out, and the year, e.g. 29 February 2016.
Use your words sparingly. Be conscious of and eliminate unnecessary words and phrases that do not add to a sentence. “That” and “which is” are good examples of unnecessarily overused words.
When you make a footnote, generally speaking, the number should go after the punctuation.
Example: If you change almost any property of a standalone layer, it will make a brief animation from the old value to the new value.[^1]
Example: Android market share is approaching 80 percent for smartphones,[^1] and the number of potential users that it can bring to a product can hardly be ignored.
An exception to this is when you have a dash — do not include a footnote after this. If you need a footnote in the sentence, then you should reword your sentence so that you can include a footnote where it is relevant.
Another exception is when a sentence appears completely in parentheses. When this happens, the footnote goes after the punctuation but before the parentheses, which follows normal punctuation rules.
When referring to a pronoun that does not reference a specific person, use the “they/their/them” form instead of the gendered “he/his/him” or “she/hers/her,” or else reword it to be neutral. This is now acceptable in many major style guides, even in the singular form.
Use Chicago style for all headings, except with ####
Capitalize: the first and last word nouns, pronouns, adjectives, verbs, adverbs, and subordinate conjunctions
Do not capitalize: articles, coordinating conjunctions, and prepositions
If you’re stuck, use this helpful tool: http://titlecapitalization.com
Use a hyphen to connect words like compound adjectives. Note this is different than an em dash (—) or en dash (–).
This stands for the Latin id est, which means “that is.” This is used to explain a concept in other wording.
Example: If your application is designed to download files automatically (i.e. not triggered by the user), you should always perform those download requests from a sequential background queue.
This stands for the Latin exemplī grātiā, which means “for the sake of example.” This is used to explain a concept with examples that demonstrate meaning or illustrate what you are saying more clearly.
Example: ...one end (e.g. the web server) is listening for connections, while the other end (e.g. our app) connects to the listening application (e.g. the web server).
In American English, i.e. and e.g. tend to have commas after them (not necessary but preferred), whereas this doesn’t occur in British English. I think it looks better without a comma, and this is more common in tech writing, so we leave it out here too.
Also, do not start a sentence with i.e. or e.g., as it is awkward and clumsy. Instead, find a different way to word your sentence.
Further reading: http://theoatmeal.com/comics/ie
To Do
A collective noun is a group of people or things that includes multiple members but is referred to as a whole. It is designated as singular (even though it implies more than one member) and takes singular verbs (e.g. is, not are) and pronouns (e.g. its, not their).
Example: Apple is definitely correct in selling it as a big new feature.
Example: Everything we discuss here has been described before in previous articles, and by Apple in its documentation.
Numbers can be tricky and have a few different rules. I will only share the ones that are relevant to objc.io.
####1. Spell out under 10.
Example: The numbers are called code points and are written in the form U+xxxx where the xxxx are four to six hexadecimal digits.
####2. Be consistent if numbers above and below 10 are in the same sentence (or in the same paragraph, referring to the same thing).
Example: ASCII is a 7-bit code that maps the English alphabet, the digits 0-9, and some punctuation and control characters into the integers 0 to 127.
In the above, because we are talking about digits/integers, they are all “the same.” And since I would not spell out 127 (it’s far too long and complicated), I want to be consistent, which means I make all the numbers as numerals.
####3. Apply common usage.
Example: Subsequently, many different 8-bit encodings were created to make computers work with languages other than English.
Yes, eight is spelled out in normal usage, but “8-bit” is far more common than “eight-bit,” so use whatever is the standard.
Further reading: http://www.grammarbook.com/numbers/numbers.asp
This is a list of words that are commonly written as two words when they are really one. Note that some of these words can be two words depending on the context, but 95% of the time when they’re used on objc.io, they are one word:
- in stead → instead
- on screen → onscreen
- re use → reuse
- straight forward → straightforward
- trade-off → tradeoff
Punctuation should (in almost every case) go inside of quotation marks. Commas and periods always go inside quotation marks. Question marks vary based on the context (though it likely will not apply here). Exceptions are dashes and colons.
Always use double quotes unless you’re using internal quotes, in which case you can use single quotes.
A semicolon is sometimes used as a super comma, but the most common instance is to connect two closely related but separate ideas. Use semicolons sparingly, and when you do, make sure the clauses on both sides of the semicolon are complete sentences; if one of them is a fragment, you are using the semicolon incorrectly.
Use ' for an apostrophe and " " for quotation marks. Do not use ` or `` or any other variation.
To Do
Use “that” for restrictive clauses and “which” for nonrestrictive clauses. Additionally, restrictive clauses do not require commas, while nonrestrictive clauses do.
Some words can be both verbs and nouns, but the way they appear changes based on what they are. Usually this means that the verb is two words and the noun is one word.
Example: He set up the computer setup.
Example: She backed up her data and saved the backup to her portable drive.
Note that these are wordy examples that aren’t really the best sentence composition, but hopefully they illustrate the difference between how the same word can be used as a verb and as a noun.
When writing any word such as towards, forwards, afterwards, upwards, backwards, etc., drop the “s.” While the words essentially mean the same, American English dictates removing the “s,” making these words toward, forward, afterward, upward, backward, etc.