Treehouse Intermediate Course - Part 2 (API Design Guidelines 2)
So, feeling still buoyed by my fresh new Treehouse approach, I'm getting another entry done - two in a day baby! Some before and some after dinner. I actually went a little further than I thought I did earlier, so that's good.
Start Time - 18:05
Prepositional vs Grammatical Phrases
Well the advantage here is that I'm a native English speaker. Now we're focusing on the English language!
Not only am I native but I actually love grammar. The rules, the exceptions...part of the reason why Swift is perfect for me!
Prepositions - where something is. Or when something happened (technically that's more of a conjunction).
Function move. I assume we need moveTo. Yes - moveTo for the function name. Or have to as the argument label.
Yes the below makes more sense.
In another example, you need to put the preposition into the function name - if there are two argument labels, this is an exception to the rule.
Extra Reading
So straight from this website - https://swift.org/documentation/api-design-guidelines/#general-conventions
A similar example to Pasan's. Where you need several arguments, it is better to have the preposition in the function name. Yes, I get that.
Naming Methods Recap
Moving straight on - a useful recap video!
We want them to read like grammatical English phrases. It can be grammatical, prepositional or neither.
Prepositional I have just covered.
Base name - the main name of the function.
Three main guidelines - omit needless words, avoid ambiguity and compensate for weak type info.
OK sounds fine. Quiz time! Three out of four but I can see where I went wrong with one!
Side Effects and Mutation
Methods with side effects - the current state is affected. E.g. if an array mutates.
No side effects - non-mutating - base name of method should be as a noun.
Couple of examples -
-ing suffix - used in the non-mutating version above. This is all vague but Pasan keeps assuring me that not to worry too much yet!
So with nouns, it is supposed to be simpler.
Noun form for the non-mutating method.
So in the recap, if there are side-effects aka mutation then use a noun for the base name. If mutation - use a verb!
Exceptions - method pairs...
If method is best described using a verb then the imperative is used e.g. sort, add, remove etc.
If it is mutating then you need a suffix e.g. -ed, -ing
If it is better with noun e.g. distance, then noun form is used for mutating. Form prefix for mutating.
Conventions
Boolean methods - as assertions e.g. isLarger or isInRangeOf. Something where 'true' or 'false' will be returned.
Parameters - choose these names to serve documentation. Even if it's not there at use site, it should clearly document the role of the function. Default arguments...
The key thing here is to get an idea of the base rules. You need to return to these and tweak them where necessary. IT'S NOT ALL AT ONCE!
So no further reading, just the quiz to complete this particular course...4/5 not bad!
Well, that's it for this course! I think it hit me hard last time that there was NOTHING practical! All theory - which of course can be tedious! But useful to get used to these conventions. That's it for today!
Finish Time -
Start Time - 18:05
Prepositional vs Grammatical Phrases
Well the advantage here is that I'm a native English speaker. Now we're focusing on the English language!
Not only am I native but I actually love grammar. The rules, the exceptions...part of the reason why Swift is perfect for me!
Prepositions - where something is. Or when something happened (technically that's more of a conjunction).
Function move. I assume we need moveTo. Yes - moveTo for the function name. Or have to as the argument label.
Yes the below makes more sense.
In another example, you need to put the preposition into the function name - if there are two argument labels, this is an exception to the rule.
Extra Reading
So straight from this website - https://swift.org/documentation/api-design-guidelines/#general-conventions
A similar example to Pasan's. Where you need several arguments, it is better to have the preposition in the function name. Yes, I get that.
Naming Methods Recap
Moving straight on - a useful recap video!
We want them to read like grammatical English phrases. It can be grammatical, prepositional or neither.
Prepositional I have just covered.
Base name - the main name of the function.
Three main guidelines - omit needless words, avoid ambiguity and compensate for weak type info.
OK sounds fine. Quiz time! Three out of four but I can see where I went wrong with one!
Side Effects and Mutation
Methods with side effects - the current state is affected. E.g. if an array mutates.
No side effects - non-mutating - base name of method should be as a noun.
Couple of examples -
-ing suffix - used in the non-mutating version above. This is all vague but Pasan keeps assuring me that not to worry too much yet!
So with nouns, it is supposed to be simpler.
Noun form for the non-mutating method.
So in the recap, if there are side-effects aka mutation then use a noun for the base name. If mutation - use a verb!
Exceptions - method pairs...
If method is best described using a verb then the imperative is used e.g. sort, add, remove etc.
If it is mutating then you need a suffix e.g. -ed, -ing
If it is better with noun e.g. distance, then noun form is used for mutating. Form prefix for mutating.
Conventions
Boolean methods - as assertions e.g. isLarger or isInRangeOf. Something where 'true' or 'false' will be returned.
Parameters - choose these names to serve documentation. Even if it's not there at use site, it should clearly document the role of the function. Default arguments...
The key thing here is to get an idea of the base rules. You need to return to these and tweak them where necessary. IT'S NOT ALL AT ONCE!
So no further reading, just the quiz to complete this particular course...4/5 not bad!
Well, that's it for this course! I think it hit me hard last time that there was NOTHING practical! All theory - which of course can be tedious! But useful to get used to these conventions. That's it for today!
Finish Time -
Comments
Post a Comment