Treehouse Intermediate Course - Part 1 (API Design Guidelines 1)
sSo begins the recommencement of Treehouse! Yes, it's been a long time and I was certainly put off it before. This time, though, I have got a good grounding from such a range of courses, including practical projects along the way. So I'm going to do something else that's new - supplement my learning with other stuff! In each entry, I will include further reading and - where applicable - code practice! Rather than race through to get it done quickly, I'm changing my approach. Let's say that the focus is on optionals, then I will go through the content, then look at other bits on optionals - online, in Swift book etc. etc., then include some practice on playground... you get the drill!
So, I'm excited for this and, as I've said, this will be more about going deeper and getting to grips with the content each time rather than racing through. OK, let's do this!!
Start Time - 09:30
Rather than I just continue, I'm going back to the start of this section on APIs.
Why do we need guidelines?
Key point - when Swift was launched, there was no real style or guidelines. In the early days - everyone had different ways of writing Swift e.g. verbose style of objective C.
And since this, we've got to Swift 5!
The point is that since open sourcing, everyone's swift code looks pretty much the same.
Key rules to keep in mind -
Point of use - readability is crucial. When calling methods etc. more important than at definition (don't need to see all the behind the scenes!)
Clarity over brevity - going for less is more! But there is a point here - you need to make the code clear.
Extra reading -
So at this point, I want to find out how Swift has changed since Swift 3! Makes sense to, as Pasan's content is nearly three years out of date...
From this website - https://learnappmaking.com/how-to-keep-up-with-swift-changes/
Some key points here -
OK, so a useful website! Also, this guy is one I signed up to for free content but never went through with it. This could be what I do post Treehouse!
Naming Types
So it is more about the goal. I believe here it will be about verb usage in functions etc.
For the below, it is obviously very vague.
The key thing is to follow the rules for the different types.
*Paused at 9:53
*Continued at 10:20 (had to phone about HMRC stuff - all sorted!)
Swift Standard Library of names - this has all the key info.
It gives you an idea of what the naming guidelines are. There are exceptions that names should read as nouns.
Booleans are one of these! Starting property names with 'is' are assertions e.g. isEmpty.
Suffixes are another convention. E.g. -able, -ible, -ing - these are property checkers e.g. equatable, comparable or expressible - these would all be protocols.
Quiz - 5 out of 5. Whoo!
Extra Reading
So what else to read up on for this! Let's just try Swift naming conventions for now...
From - https://swift.org/documentation/api-design-guidelines/
The key fundamentals are:
So a recurring thing here is naming according to ROLE. The role of constants/variables is usually some sort of object therefore they should be nouns. But it shouldn't be just down to type constraints.
OK all that sounds fine and there's no practice needed. Time to move on - going to basically stop at the point of where I got to before. Well worth going over this as it makes much more sense compared to last August!
Naming Methods
Syntax for functions - argument labels.
External and local names. You don't need both basically. Omit using the _.
This is all recap so far.
Rule 1 - omit needless words
Example -
Base name is insert. This makes it obvious that we are inserting an element into an array, then the argument label 'element' is totally unnecessary. So we can get rid of it!
The below is better - use of the _.
But there needs to be a careful balance.
Another important rule is AVOID AMBIGUITY!
The issue here is that it is vague. It is the opposite problem of rule 1! It is a case by case evaluation to decide if more/less info is needed.
Type aliases - when using any or some objective C ones. Type information is lacking in this case - 'higher' types. They would need down casting.... Sidenote there!
So each weakly typed parameter needs a NOUN describing its ROLE.
No need to do any further reading here. The suggested website is actually the last one I used anyway!
OK, one more video and a quiz and I'm done for now. Will be doing several stints today!
Fluent Usage
Basically, the code should be grammatically English at the use site.
I think prepositions are key here e.g. at. Yes, snap!
Even better that Pasan has added - at element- so this is better at the use site.
Right, so the quiz, then that's it for now!
*Internet issues - cost 25 minutes
Quiz done - 6 out of 6!
Finish Time - 11:25 (Total time - 1 hour and 3 minutes)
A good session! Useful to go over the conventions and what all of this means. All of it makes sense and does not require actual coding practice. Definitely worth doing the extra reading where relevant - that's something I'm going to be doing regularly now, using the blue subheading. So will be doing some more this afternoon!
So, I'm excited for this and, as I've said, this will be more about going deeper and getting to grips with the content each time rather than racing through. OK, let's do this!!
Start Time - 09:30
Rather than I just continue, I'm going back to the start of this section on APIs.
Why do we need guidelines?
Key point - when Swift was launched, there was no real style or guidelines. In the early days - everyone had different ways of writing Swift e.g. verbose style of objective C.
And since this, we've got to Swift 5!
The point is that since open sourcing, everyone's swift code looks pretty much the same.
Key rules to keep in mind -
Point of use - readability is crucial. When calling methods etc. more important than at definition (don't need to see all the behind the scenes!)
Clarity over brevity - going for less is more! But there is a point here - you need to make the code clear.
Extra reading -
So at this point, I want to find out how Swift has changed since Swift 3! Makes sense to, as Pasan's content is nearly three years out of date...
From this website - https://learnappmaking.com/how-to-keep-up-with-swift-changes/
Some key points here -
- Swift has a migration tool - that means it helps upgrade Swift to the current language. You'll have to review each option to do this.
- Between Swift 2 and 3 were a LOT of changes. Before that we had lots of Objective C style content, which was changed. So learning around that time would have meant re-learning - that makes sense! 2016 actually had the biggest changes - after my initial learning! So this confirms to me that I was actually right to relearn the core concepts again.
- Swift 4 and 5 don't have anywhere near the number of changes. That's good to know.
OK, so a useful website! Also, this guy is one I signed up to for free content but never went through with it. This could be what I do post Treehouse!
Naming Types
So it is more about the goal. I believe here it will be about verb usage in functions etc.
For the below, it is obviously very vague.
The key thing is to follow the rules for the different types.
*Paused at 9:53
*Continued at 10:20 (had to phone about HMRC stuff - all sorted!)
Swift Standard Library of names - this has all the key info.
It gives you an idea of what the naming guidelines are. There are exceptions that names should read as nouns.
Booleans are one of these! Starting property names with 'is' are assertions e.g. isEmpty.
Suffixes are another convention. E.g. -able, -ible, -ing - these are property checkers e.g. equatable, comparable or expressible - these would all be protocols.
Quiz - 5 out of 5. Whoo!
Extra Reading
So what else to read up on for this! Let's just try Swift naming conventions for now...
From - https://swift.org/documentation/api-design-guidelines/
The key fundamentals are:
- Clarity at the point of use - methods/properties etc. declared only once but used many times.
- Clarity over brevity - shouldn't take this so far that the code is hard to understand! It is NOT a goal to go for the smallest code!
- Documentation comment - use this as a running commentary. Very useful when looking back on code - I don't do this but see that it would be useful!
So a recurring thing here is naming according to ROLE. The role of constants/variables is usually some sort of object therefore they should be nouns. But it shouldn't be just down to type constraints.
OK all that sounds fine and there's no practice needed. Time to move on - going to basically stop at the point of where I got to before. Well worth going over this as it makes much more sense compared to last August!
Naming Methods
Syntax for functions - argument labels.
External and local names. You don't need both basically. Omit using the _.
This is all recap so far.
Rule 1 - omit needless words
Example -
Base name is insert. This makes it obvious that we are inserting an element into an array, then the argument label 'element' is totally unnecessary. So we can get rid of it!
The below is better - use of the _.
But there needs to be a careful balance.
Another important rule is AVOID AMBIGUITY!
The issue here is that it is vague. It is the opposite problem of rule 1! It is a case by case evaluation to decide if more/less info is needed.
Type aliases - when using any or some objective C ones. Type information is lacking in this case - 'higher' types. They would need down casting.... Sidenote there!
So each weakly typed parameter needs a NOUN describing its ROLE.
No need to do any further reading here. The suggested website is actually the last one I used anyway!
OK, one more video and a quiz and I'm done for now. Will be doing several stints today!
Fluent Usage
Basically, the code should be grammatically English at the use site.
I think prepositions are key here e.g. at. Yes, snap!
Even better that Pasan has added - at element- so this is better at the use site.
Right, so the quiz, then that's it for now!
*Internet issues - cost 25 minutes
Quiz done - 6 out of 6!
Finish Time - 11:25 (Total time - 1 hour and 3 minutes)
A good session! Useful to go over the conventions and what all of this means. All of it makes sense and does not require actual coding practice. Definitely worth doing the extra reading where relevant - that's something I'm going to be doing regularly now, using the blue subheading. So will be doing some more this afternoon!
Comments
Post a Comment