-
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
Don’t use it. There is a time and place for British English, but we use American English because it is the standard within this community.
When in doubt, look up a word in a dictionary for the proper usage.
Further reading: http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences
When using a colon in a normal sentence (i.e. not introducing something, as outlined below), do not capitalize the first word after the colon if the entire following thought is one sentence.
Example: Using UIView or CAAnimation animations has two big problems when it comes to interactive animations: those 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.
However, if the explanation after the colon consists of more than one sentence to explain what came before it, then the first word after the colon should be capitalized.
Example: The function recvfrom(2) expects two arguments: The first argument is the socket address sin_other, which is the socket we want to receive data from. The second argument is a pointer to a buffer, into which the data will be written.
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.
Contractions should be used sparingly, but use your best judgement about what sounds correct. Sometimes a sentence reads better with two words joined together, but other times it reads best with the words spelled out. Go with what feels natural to you. However, 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, so long as a consistent style is used throughout.
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).
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 gendered pronoun that doesn’t reference a specific person, always use both male and female. While it may read less clunky using only one or the other, it’s important to be mindful of the programming/tech industry, and the fact that discrimination toward and harassment of women is prevalent. Changing your language to be inclusive is simply one way to work against this.
Better yet, reword it to use neutral language.
Example: One of the things almost every app developer has to do in his or her life is import things from a web service into Core Data.
Example: One of the things almost every app developer has to do in life is import things from a web service into Core Data.
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
To Do
To Do
To Do
To 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.