I keep encountering people saying self-documenting code is pointless or a fad and this helps restore my sanity. I feel like a lot of these come naturally if you're an empathetic person and can put yourself in others shoes or your own, years later.
Long time creeper of the channel but finally getting into my first app. This channel has been a lifesaver. Thanks for all the time and hard work you've put into this Brian. It's definitely helped a TON of people
i dont mean to be offtopic but does anyone know a tool to log back into an instagram account? I was dumb forgot the login password. I love any tips you can give me
I see what you are saying you have a good point. It is hard coming from a java background where the professor requires you to comment all your code otherwise you get a zero. Keep up the good work.
Yeah I've taken numerous classes where they basically want comments for every line, and it becomes very redundant. I was following one of your Swift courses and thought to myself about how you have very little comments, often just for temporary things that we change up when we are ready. This video really clears that up, thanks!
Great to hear that Austin, as far as I know schools don't emphasize self-documenting coding practices. In the real world, almost all professionals develop software this way. It'll become even more evident once you join a software organization that knows what they're doing.
Another tip for beginners is chose a naming convention and stick to it. For instance don’t name one function - FunctionName() then somewhere else in the code name a different function - anotherFunction(). Choose between full capitalisation, or humpback, or none, but stick with it, don’t mix and match
Good content. :) Personally I use two simple concepts for Comments. Responsibility: I think this is your "why". A Comment should define the responsibility of this part (class, function, method, module etc) of the Code. In Line Comments are a bad thing they are telling yourself, "dude your code is too complicated". This brings up your "don't comment what you are doing". If a responsibility is described with the word "and" it`s getting to big. This is another responsibility and should have its own part in the code. This simple principle will reduce the complexity of the code on the fly, because you separate responsibilities. This will lower the need of explanations of what this part of code is doing because it has got a single responsibility. For example, "calculate 1 + 1 AND divide by 2". These are two responsibilities. So, if you comment a part of your code before you implement it, you get a feeling for a "bad smell" of what you are planning to do. Design by Contract: For me a part of code is a Blackbox. I don’t know what is inside of it and I don’t want to know if I don’t have to. I don’t want to understand how this part is archiving its responsibility I just want to know what it is archiving. So, responsibilities are one aspect of this "black box". Another one is the "in" and "out" of this box of code. Parameters and Return values are your contract. You don’t really have to care about what this part of the code is doing, we have a contract, if I give this to you, I will get back that". I trust the code and the person who made it. If this doesn’t work, I or someone else got some work to do, bringing the contract and the part of the code on pair. If you use these concepts you get a simple general principle on pair with decomposition thinking of IT people. Furthermore it`s easy to transfer this kind of commented code into class/component diagrams and explain others your work without talking about details other people don’t care about or don’t understand. And that`s legit. I don’t expect some business guy to understand my code like I don’t understand his way of optimisation a production line. We both are able to, but this is a waste of our time. Talking about responsibilities is a metaphor most people can understand, without diving to deep into the matrix. At the same time, you can abstract and concrete your code. Do you want to talk about components? Or do you want to dive into components and talk on class level? Or do you even want to dive into class level and talk about methods? Or do you have the need to dive into concrete methods because something is going wrong at this single point? This will increase your and their efficiency and they will be thankful. So, comments can be more than explanations, they can be used to build structure and to communicate with you team without saying a single word. 😊
when I develop something like a library, for example for cocoapod, I try to add doc-comments everywhere because I generate documentation from them and because it must be really easy to use. the problem about non-updated comments exists because often a dev doesn't change it, so probably it's a bad habit of a single person.
I tend to make use of multiple arguments for the same parameter: func showAlert(for title: String, with message: String) Which makes the calls even more readable: let title = "Hello" let message = "My name is..." showAlert(for: title, with: message)
Awesome idea. I noticed that Swift 4 changed a lot of the functions to that style of naming where instead of having something like forKey(key: String) the argument would just be called forKey.
There's nothing worse than opening a overly commented project. As if code wasn't overwhelming enough. I think well named functions and variables do the trick. // TODO: Buy milk // Here, I went the shop. // This is a function.
Lets Build That App “I’m god” haha. I really am grateful for everything you’ve done on the channel, it’s really helped me more than you can ever imagine. Appreciate cha ;) Also, a video idea: What are your thoughts on “experienced” Stackoverflow users attacking inexperienced programmers like a pack of animals when they simply word something that they don’t quite understand wrong
It's the opposite extreme of Impostor syndrome, it stems from insecurities of programmers that are a bit too confident in the small amount of knowledge they have.
Lets Build That App I miss the days of being able to ask a question that won’t be judged, won’t affect my score and getting a direct answer or links to something that might be somewhat useful
Unit tests quickly become obsolete when code changes. Should we not do that either? People seriously need to stop using the phrase "self-documenting" as it convinces junior developers (even those with "senior" in their title) that their code is "good" because they use descriptive variable names. If you're bad at documenting your code, you're bad at writing code.
Hi brian i am a beginner in iOS development. Thanks for the tutorial. Could you please give info and tips about the ios app size ? I mean sometimes i think my app size is too big just for simple app and i don't why and how to make it thinner. Thank you very much for your videos
nice video! I usually write this line showAlert(forTtitle title: String, message: String) instead of showAlertForTitle(_ title: String, message: String) to make it shorter
How about some Swift special comment keywords? Such as // MARK: // TODO: and // FIXME: . I like those special comments to help me to manage my codes. By running some social scripts on project, we can find out those special comment keywords like TODO and FIXME.
Hi Brian, I needed one help with the stock public api that would give me JSON value. I Tried YQL and yahoo finance and google finance api which I thought to be free api. But couldn't get data, Some of these api are broken now and don't give data. Do you know or could find any stock api that would give me basic vale as stock price, high , low, daily price, weekely , yearly , 52 weeks high and low. I am working on stock app that require these information. Thank you for your help.
I do not comment code when your variables and methods are named properly. Naming your variables and methods properly are self documenting. The only time I add a comment is when the code itself is hard to explain, and it is impossible to refactor. Also, comments can lie too when a developer changes the implentation of the method or whatever and forgets to update the comments.
All I want to know is how to be able to comment onto CZcams videos (especially who I’m subscribed to ? 😟 anyone out there who could help me? Sorry if my question has nothing to do with this site
Your reasons for why do we comment are wrong. The most important reason is to describe API utilisation and to describe class intent. It is a tool to ease the visualization of roles in the system.
I keep encountering people saying self-documenting code is pointless or a fad and this helps restore my sanity. I feel like a lot of these come naturally if you're an empathetic person and can put yourself in others shoes or your own, years later.
Thank you for the great content! A clear explanation about when to leave comments can be hard to come by.
Long time creeper of the channel but finally getting into my first app. This channel has been a lifesaver. Thanks for all the time and hard work you've put into this Brian. It's definitely helped a TON of people
i dont mean to be offtopic but does anyone know a tool to log back into an instagram account?
I was dumb forgot the login password. I love any tips you can give me
I see what you are saying you have a good point. It is hard coming from a java background where the professor requires you to comment all your code otherwise you get a zero. Keep up the good work.
It’s common for professors to force this type of coding style. However in the real world comments should not be used unnecessarily.
Yeah I've taken numerous classes where they basically want comments for every line, and it becomes very redundant. I was following one of your Swift courses and thought to myself about how you have very little comments, often just for temporary things that we change up when we are ready. This video really clears that up, thanks!
Great to hear that Austin, as far as I know schools don't emphasize self-documenting coding practices. In the real world, almost all professionals develop software this way. It'll become even more evident once you join a software organization that knows what they're doing.
Another tip for beginners is chose a naming convention and stick to it. For instance don’t name one function - FunctionName() then somewhere else in the code name a different function - anotherFunction(). Choose between full capitalisation, or humpback, or none, but stick with it, don’t mix and match
Good content. :) Personally I use two simple concepts for Comments.
Responsibility: I think this is your "why". A Comment should define the responsibility of this part (class, function, method, module etc) of the Code. In Line Comments are a bad thing they are telling yourself, "dude your code is too complicated". This brings up your "don't comment what you are doing". If a responsibility is described with the word "and" it`s getting to big. This is another responsibility and should have its own part in the code. This simple principle will reduce the complexity of the code on the fly, because you separate responsibilities. This will lower the need of explanations of what this part of code is doing because it has got a single responsibility. For example, "calculate 1 + 1 AND divide by 2". These are two responsibilities. So, if you comment a part of your code before you implement it, you get a feeling for a "bad smell" of what you are planning to do.
Design by Contract: For me a part of code is a Blackbox. I don’t know what is inside of it and I don’t want to know if I don’t have to. I don’t want to understand how this part is archiving its responsibility I just want to know what it is archiving. So, responsibilities are one aspect of this "black box". Another one is the "in" and "out" of this box of code. Parameters and Return values are your contract. You don’t really have to care about what this part of the code is doing, we have a contract, if I give this to you, I will get back that". I trust the code and the person who made it. If this doesn’t work, I or someone else got some work to do, bringing the contract and the part of the code on pair.
If you use these concepts you get a simple general principle on pair with decomposition thinking of IT people. Furthermore it`s easy to transfer this kind of commented code into class/component diagrams and explain others your work without talking about details other people don’t care about or don’t understand. And that`s legit. I don’t expect some business guy to understand my code like I don’t understand his way of optimisation a production line. We both are able to, but this is a waste of our time. Talking about responsibilities is a metaphor most people can understand, without diving to deep into the matrix. At the same time, you can abstract and concrete your code. Do you want to talk about components? Or do you want to dive into components and talk on class level? Or do you even want to dive into class level and talk about methods? Or do you have the need to dive into concrete methods because something is going wrong at this single point? This will increase your and their efficiency and they will be thankful.
So, comments can be more than explanations, they can be used to build structure and to communicate with you team without saying a single word. 😊
I am always looking for videos like this since I will be graduating university in December and will be looking for a software development job. Thanks!
I still don't know how you only have 88k subscribers!
Such amazing content
Yeah, takes time to build an audience, we'll just keep growing from here.
I think on positive side there are 88K swift developer who is dependent on his teaching..... I think that is quite a bit audience ... :)
Indeed 88K is a good number, can't expect a channel to grow too quickly that talks about something as dense as iOS dev.
when I develop something like a library, for example for cocoapod, I try to add doc-comments everywhere because I generate documentation from them and because it must be really easy to use.
the problem about non-updated comments exists because often a dev doesn't change it, so probably it's a bad habit of a single person.
I tend to make use of multiple arguments for the same parameter:
func showAlert(for title: String, with message: String)
Which makes the calls even more readable:
let title = "Hello"
let message = "My name is..."
showAlert(for: title, with: message)
Indeed, this is what I do as well.
Awesome idea. I noticed that Swift 4 changed a lot of the functions to that style of naming where instead of having something like forKey(key: String) the argument would just be called forKey.
Great advice & nice examples - agree completely!
Do you generate docs? For instance Jazzy? Then comments are needed.
There's nothing worse than opening a overly commented project. As if code wasn't overwhelming enough. I think well named functions and variables do the trick.
// TODO: Buy milk
// Here, I went the shop.
// This is a function.
Haha.
//Oh look at how great the implementation is here
//I'm a god
Lets Build That App “I’m god” haha. I really am grateful for everything you’ve done on the channel, it’s really helped me more than you can ever imagine. Appreciate cha ;)
Also, a video idea: What are your thoughts on “experienced” Stackoverflow users attacking inexperienced programmers like a pack of animals when they simply word something that they don’t quite understand wrong
It's the opposite extreme of Impostor syndrome, it stems from insecurities of programmers that are a bit too confident in the small amount of knowledge they have.
Lets Build That App I miss the days of being able to ask a question that won’t be judged, won’t affect my score and getting a direct answer or links to something that might be somewhat useful
Awsome tips. Thank you.
Another great video - thanks!
Thankyou
Unit tests quickly become obsolete when code changes. Should we not do that either? People seriously need to stop using the phrase "self-documenting" as it convinces junior developers (even those with "senior" in their title) that their code is "good" because they use descriptive variable names. If you're bad at documenting your code, you're bad at writing code.
Hi brian i am a beginner in iOS development. Thanks for the tutorial. Could you please give info and tips about the ios app size ? I mean sometimes i think my app size is too big just for simple app and i don't why and how to make it thinner. Thank you very much for your videos
Hey buddy. Great content.. WHy don't you make video on making android application or that's related to Java?
Search the channel for android videos
nice video!
I usually write this line
showAlert(forTtitle title: String, message: String)
instead of
showAlertForTitle(_ title: String, message: String)
to make it shorter
Wasim Alatrash me too! I think look more like a swit3/4 naming convention. The approach in the video it’s more like swift 2 style.
Yeah, exactly! I see people write it in both ways, but I prefer the first approach!
Whoops I let my old Swift 2 ways into the video
What about coding comments as notes while learning
thank you
very helpful
How about some Swift special comment keywords? Such as // MARK: // TODO: and // FIXME: . I like those special comments to help me to manage my codes. By running some social scripts on project, we can find out those special comment keywords like TODO and FIXME.
Yeah anything that helps you fix bugs is always helpful I find
Hi Brian, I needed one help with the stock public api that would give me JSON value. I Tried YQL and yahoo finance and google finance api which I thought to be free api. But couldn't get data, Some of these api are broken now and don't give data. Do you know or could find any stock api that would give me basic vale as stock price, high , low, daily price, weekely , yearly , 52 weeks high and low. I am working on stock app that require these information. Thank you for your help.
hi , how i can increase the navigation bar and style it to look like curved shape ?
"it's a wrong expectation that a programmer who couldn't organise his/her code will be succint and clear in the comments" ... i paraphrase
I do not comment code when your variables and methods are named properly. Naming your variables and methods properly are self documenting. The only time I add a comment is when the code itself is hard to explain, and it is impossible to refactor. Also, comments can lie too when a developer changes the implentation of the method or whatever and forgets to update the comments.
Very true.
what architecture pattern do you use frequently ? i wanna hear your opinion about mvvm or even viper :D
I use a combination of a bunch of best practices for iOS development, no specific arch
All I want to know is how to be able to comment onto CZcams videos (especially who I’m subscribed to ? 😟 anyone out there who could help me? Sorry if my question has nothing to do with this site
Your reasons for why do we comment are wrong. The most important reason is to describe API utilisation and to describe class intent. It is a tool to ease the visualization of roles in the system.
This is geared towards beginners, who usually over comment their code with wrong/obsolete description.
Lets Build That App a quick tutorial on how to build pinterest layout
raywenderlich has a good tutorial on this, have read it?
thanks I'm going to take a look at it
Have you tried Literate Programming?
I have not, but the philosophy behind it sounds interesting.
Hi
It’s litty & England is my city
HELLO. I am currently lloking to hire someone to build a new application. Please let me know if you want to talk about details.
Awesome, hope you find the right person.
Lets Build That App so you do not want to help me build it?
I never comment. I dont ever really have a need to