The ONLY Right Way to Document Your Code
ฝัง
- เผยแพร่เมื่อ 4 ต.ค. 2024
- In this video I'll share what you need to know in order to write a good code documentation and make your codebase as readable as possible.
⭐ Courses with real-life practices
⭐ Save countless hours of time
⭐ 100% money back guarantee for 30 days
⭐ Become a professional Android developer now:
pl-coding.com/...
Get my FREE PDF about 20 things you should never do in Jetpack Compose:
pl-coding.com/...
💻 Let me be your mentor and become an industry-ready Android developer in 10 weeks:
pl-coding.com/...
Get the initial source code here:
github.com/phi...
Get the final source code here:
github.com/phi...
Regular programming advice on my Instagram page: / _philipplackner_
Join my Discord server:
/ discord
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 👍🏼
So nice and clear , thank you man❤
Learned something new today 🎉. Thanks for sharing this Philipp!✌️
Glad you liked it!
Awesome tutorial ❤
This was timely, thanks for sharing.
Very helpful video, thank you, Philipp
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 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!
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
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.
Hi Philipp, can you make a video about how to sync data between remote and local? also for cases theres inflict happen
Ty for remind of right way of comments.
I think that hasSufficientAmount should be an extension function rather than instance function. Arguments like fee are not related to the account object.
This is great! I'm expecting soon JetBrains/Google to implement it through generative AI documentation (Android Studio and JetBrains Ultinate IDEs)
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)
very very useful steps
The video has suddenly changed the viewpoint of coding !
Nice and useful 😊
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
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?
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 🚀👍
Good
04:46 I know what you wanted to say there,
😂 nice comedy show!
🔥🔥
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.
No way, I was just looking for a public talk about documenting source code today 😅
Please make a series on Android hardware
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.
I'm a grandma reading und writing code, so don't make such grandma jokes 😂😂😂
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