Very good. I would just add that adding a good constant name for the 500 could make it even more clean with the constant with a comment on what it’s used for. I also always try to minimize the amount of parameters, but clearly it’s not always possible
I keep toying with the idea of creating a cheat sheet for PR reviews, for things to keep in mind. There's some good stuff in here that I think I will consider adding to that. Love the videos, thanks for sharing!
7:31 why not use the “extract function” in the refactoring menu instead of manually doing this? Using the refactoring tools is important developer skill
@@PhilippLackner try them, they're great productivity tools, trivial to use, and offer some protection against "manual" mistakes (which are bound to creep in, especially if you're refactoring a lot)
13:27 lines 27 - 31 can still be refactored to not need a comment. It's crazy how 33- 37 looks just like a Rust if-let wrapping a let-else... statement.
Thank you for this video. In my opinion, other than for public facing APIs on module boundaries, there is no reason to have any comments in code. 1) Hacks or technical workarounds: You can encode the why in function names themselves. So, if you need to perform a hack, then just make a function that has the why in its name. Comments often go stale or even get lost in refactoring. Code does not. I have even seen comments outlive the code they attempted to describe. 2) Unit tests are also a better solution to comments. If you have some weird code for some random business requirement, add a test for it instead. Then, this requirement will be captured programmatically. Comments do not ensure we are fulfilling our business requirements, but unit tests do. Comments were probably useful when languages were much less expressive, but today we have programming languages that can capture our intent almost perfectly in the code itself. This is why I do not write comments in my code. If the code does not explain itself well, then it is better to invest in making the code itself more expressive
I think that hasSufficientAmount should be an extension function rather than instance function. Arguments like fee are not related to the account object.
Then you would need to create an instance of the class just to call the function. You are then using the class as a namespace, not sure why you need to overcomplicate using a class… are you going to change the implementation for testing?
@@ChrisAthanas SOLID principles... every function and every class should have one job. So you had to create a validation interactor and you have to have a payment interactor that do payment operation. Payment interactor should take validation interactor as constructor parameter ... for testing you gonna test your interactors and mock them whenever needed
Thanks man. I have one question. You threw an exception alongside returning failure results. Is this standard practice? When should you throw exceptions instead of returning a failure, and should you intermix them? I understand this was about comments primarily
Exception is always for the dev, to help find and resolve a problem, and the result is always for the user. In this case, i think it doesnt really makes sense to have the exception, because you can just return a failiure there and notify the user about whats wrong (amount cant be negative in this example). unless you want to notify a fellow dev that amount can never be negative so he can make sure that no negative value will ever reach this function. I do have a better example for this. Lets have a theme.json file that has colors that can be referenced with a string like this: "main/text/color", and has a value of something like "#FFFFFF". When i try to resolve this color with a function, i usually like to throw an exception here, that contains the reference if something goes wrong. So the exception looks something like this: ColorResolveException(""Failed to resolve color for $colorRef") With this if i see this exeption i immediately know where to look for the problem (the json file, to see if that reference exists or not). and if i you need to return results with lets say, operation messages like in Philip's example then i can go like he did, but without the exception because that just doesnt make sense here.
If you're familiar with doxygen, there's a similar tool called dokka that can generate HTML documentation as well. Doxygen doesn't currently have support for kotlin.
Great video Phillip, Could it be a better approach if we make hasSufficientFunds a usecase so that the logic inside could be tested. Please share your thoughts.
@@ChrisAthanas i wouldn't recommend squashing ALL the commits for a PR, unless it's a really small PR to begin with generally speaking, while i'm on a local branch, i treat commits like "backups", like saving a document i'm working on. even if i'm doing exploratory programming - trying things out just to see what works best - my commits will be like checkpoints, in case if i want to get back to the previous approach without having to manually backpeddle out of my recent changes in 12 files then you can use rebase interactive to properly clean up the history before you push the branch rebase interactive gives you a much more fine-grained control, you can squash commits, rephrase their messages, reorder them, skip some etc.
sure - it depends what you consider as "documented" though. unless you're writing a library or an SDK, you will not usually need KDoc nor creating actual documents : ) clean code + maintainable, readable and comprehensive tests + well described PR are enough of a documentation
Very good. I would just add that adding a good constant name for the 500 could make it even more clean with the constant with a comment on what it’s used for. I also always try to minimize the amount of parameters, but clearly it’s not always possible
Yes 👍🏼
Learned something new today 🎉. Thanks for sharing this Philipp!✌️
Glad you liked it!
Awesome tutorial ❤
I keep toying with the idea of creating a cheat sheet for PR reviews, for things to keep in mind. There's some good stuff in here that I think I will consider adding to that. Love the videos, thanks for sharing!
Happy to help!
So nice and clear , thank you man❤
7:31 why not use the “extract function” in the refactoring menu instead of manually doing this?
Using the refactoring tools is important developer skill
I've never gotten used to these 😅
@@PhilippLackner try them, they're great productivity tools, trivial to use, and offer some protection against "manual" mistakes (which are bound to creep in, especially if you're refactoring a lot)
This was timely, thanks for sharing.
Very helpful video, thank you, Philipp
13:27 lines 27 - 31 can still be refactored to not need a comment.
It's crazy how 33- 37 looks just like a Rust if-let wrapping a let-else... statement.
Awesome video I learnt alot. I always find myself writing code for my grandma 😂😂😂
Let’s see your repo and let us judge if it’s grandma level
Thank you for this video. In my opinion, other than for public facing APIs on module boundaries, there is no reason to have any comments in code.
1) Hacks or technical workarounds: You can encode the why in function names themselves. So, if you need to perform a hack, then just make a function that has the why in its name. Comments often go stale or even get lost in refactoring. Code does not. I have even seen comments outlive the code they attempted to describe.
2) Unit tests are also a better solution to comments. If you have some weird code for some random business requirement, add a test for it instead. Then, this requirement will be captured programmatically. Comments do not ensure we are fulfilling our business requirements, but unit tests do.
Comments were probably useful when languages were much less expressive, but today we have programming languages that can capture our intent almost perfectly in the code itself. This is why I do not write comments in my code. If the code does not explain itself well, then it is better to invest in making the code itself more expressive
I think that hasSufficientAmount should be an extension function rather than instance function. Arguments like fee are not related to the account object.
is it okay to write all the validation code in a function? Would creating a PaymentValidation class be better ?
Yes you could do that
Then you would need to create an instance of the class just to call the function. You are then using the class as a namespace, not sure why you need to overcomplicate using a class… are you going to change the implementation for testing?
@@ChrisAthanas pretty much the definition of a use case haha
@@ChrisAthanas SOLID principles... every function and every class should have one job. So you had to create a validation interactor and you have to have a payment interactor that do payment operation. Payment interactor should take validation interactor as constructor parameter ... for testing you gonna test your interactors and mock them whenever needed
@@sadighasanzade ooof... maybe a function is the simplest solution here
I'm not a fan overcomplicating
This is great! I'm expecting soon JetBrains/Google to implement it through generative AI documentation (Android Studio and JetBrains Ultinate IDEs)
Ty for remind of right way of comments.
The video has suddenly changed the viewpoint of coding !
Nice and useful 😊
Hi Philipp, can you make a video about how to sync data between remote and local? also for cases theres inflict happen
Thanks man. I have one question. You threw an exception alongside returning failure results. Is this standard practice? When should you throw exceptions instead of returning a failure, and should you intermix them? I understand this was about comments primarily
Exception is always for the dev, to help find and resolve a problem, and the result is always for the user. In this case, i think it doesnt really makes sense to have the exception, because you can just return a failiure there and notify the user about whats wrong (amount cant be negative in this example). unless you want to notify a fellow dev that amount can never be negative so he can make sure that no negative value will ever reach this function.
I do have a better example for this.
Lets have a theme.json file that has colors that can be referenced with a string like this: "main/text/color", and has a value of something like "#FFFFFF".
When i try to resolve this color with a function, i usually like to throw an exception here, that contains the reference if something goes wrong.
So the exception looks something like this:
ColorResolveException(""Failed to resolve color for $colorRef")
With this if i see this exeption i immediately know where to look for the problem (the json file, to see if that reference exists or not).
and if i you need to return results with lets say, operation messages like in Philip's example then i can go like he did, but without the exception because that just doesnt make sense here.
Appreciate the time it took to write this thanks that helped@@gergokocsis3288 🚀👍
very very useful steps
Is it possible to generate page document with Kotlin just like with Javadoc?
This video is describing Kdoc, which is the Kotlin version of jdoc
So not sure what you’re asking here?
@@ChrisAthanas generated doc in HTML
@@bitwisedevs469 ok, why do you need that when the IDE has all that?
If you're familiar with doxygen, there's a similar tool called dokka that can generate HTML documentation as well. Doxygen doesn't currently have support for kotlin.
Great video Phillip, Could it be a better approach if we make hasSufficientFunds a usecase so that the logic inside could be tested. Please share your thoughts.
What makes it untestable right now?
Does anybody know is there a video guide how often to commit to git while writing the code somewhere?
There is no standards and there is a push to squash all those committees into a single commit for a PR
@@ChrisAthanas i wouldn't recommend squashing ALL the commits for a PR, unless it's a really small PR to begin with
generally speaking, while i'm on a local branch, i treat commits like "backups", like saving a document i'm working on.
even if i'm doing exploratory programming - trying things out just to see what works best - my commits will be like checkpoints, in case if i want to get back to the previous approach without having to manually backpeddle out of my recent changes in 12 files
then you can use rebase interactive to properly clean up the history before you push the branch
rebase interactive gives you a much more fine-grained control, you can squash commits, rephrase their messages, reorder them, skip some etc.
04:46 I know what you wanted to say there,
I'm a grandma reading und writing code, so don't make such grandma jokes 😂😂😂
🔥🔥
😂 nice comedy show!
Good
No way, I was just looking for a public talk about documenting source code today 😅
Please make a series on Android hardware
Work not documented is work not done
sure - it depends what you consider as "documented" though.
unless you're writing a library or an SDK, you will not usually need KDoc nor creating actual documents : )
clean code + maintainable, readable and comprehensive tests + well described PR are enough of a documentation