How to Document Your Code Like a Pro

Подписаться 239 тыс.

Просмотров 82 тыс.

50% 1

In this video, I’ll share the essential principles for creating clear, concise, and effective code documentation. From commenting to docstrings, you’ll learn how to make your code documentation shine and improve accessibility for others.
Git Repo: git.arjan.codes/2023/doc
✍🏻 Take a quiz on this topic: www.learntail.com/quiz/xkfiyp
🚀 Next-Level Python Skillshare Class: skl.sh/3ZQkUEN
👷 Join the FREE Code Diagnosis Workshop to help you review code more effectively using my 3-Factor Diagnosis Framework: www.arjancodes.com/diagnosis
💻 ArjanCodes Blog: www.arjancodes.com/blog
🎓 Courses:
The Software Designer Mindset: www.arjancodes.com/mindset
The Software Designer Mindset Team Packages: www.arjancodes.com/sas
The Software Architect Mindset: Pre-register now! www.arjancodes.com/architect
Next Level Python: Become a Python Expert: www.arjancodes.com/next-level...
The 30-Day Design Challenge: www.arjancodes.com/30ddc
🛒 GEAR & RECOMMENDED BOOKS: kit.co/arjancodes.
👍 If you enjoyed this content, give this video a like. If you want to watch more of my upcoming videos, consider subscribing to my channel!
💬 Discord: discord.arjan.codes
🐦Twitter: / arjancodes
🌍LinkedIn: / arjancodes
🕵Facebook: / arjancodes
📱Instagram: / arjancodes
♪ Tiktok: / arjancodes
👀 Code reviewers:
- Yoriz
- Ryan Laursen
- James Dooley
- Dale Hagglund
🎥 Video edited by Mark Bacskai: / bacskaimark
🔖 Chapters:
0:00 Intro
1:01 Code documentation
3:02 #1 Comments
6:46 #2 Type hints
10:44 #3 Docstrings
13:24 #4 ChatGPT
15:20 #5 mkdocs
17:22 Final thoughts
#arjancodes #softwaredesign #python
DISCLAIMER - The links in this description might be affiliate links. If you purchase a product or service through one of those links, I may receive a small commission. There is no additional charge to you. Thanks for supporting my channel so I can continue to provide you with free content each week!

Опубликовано:

22 июн 2024

Ссылка:

Скачать:

Готовим ссылку...

Добавить в:

Мой плейлист

Посмотреть позже

Комментарии : 82

@ArjanCodes 8 месяцев назад

👷 Join the FREE Code Diagnosis Workshop to help you review code more effectively using my 3-Factor Diagnosis Framework: www.arjancodes.com/diagnosis

@rrwoodyt Год назад

I like the idea of making the code fairly self-documenting by making good choices of class/function/var names. And adding comments that explain WHY things are being done, not how. My merge requests are reviewed by someone else, so it's a fun challenge to make sure everything is clear enough that the reviewer won't ask me any annoying questions. And yes, I want to make sure then when I come back in a year or two, it's easy for me to remember what the heck I was doing in the code...

@spaderkungskuk Год назад

Yes the why is what matters. And when that explanation becomes too hard to understand it’s time to refactor :)

@DagarCoH 8 месяцев назад

I want to add to these remarks that I feel grouping code that does work on the same aspect of your system is also very important for understanding and maintaing your code base. If you have a class that has many hundreds or even thousands of lines of code, identify all the different things it does, re-organize the code to group together functions that have the same context, and then refactor that out into different modules/classes. That makes your code base much easier to understand, search through and adapt.

@aliwelchoo Год назад

Definitely leaning more towards self documenting myself after trying out full docstrings and then autodoc with sphinx. Navigating the code is an important part of readability

@skytree278 11 месяцев назад

Summary: - Code should be written in a way that promotes readability and is easy to understand for other developers. - Good documentation can take different forms such as comments, documentation sites, and API documentation. - Comments should provide meaningful explanations and not simply describe the syntax of the code. - Using type hints in Python code improves clarity and understanding. - Docstrings can be used to document functions, methods, classes, and modules, and tools like Auto docstring can assist in generating them.

@BorgPrincess Год назад

Very good points. Whenever I have just spent an hour figuring out how something works, I fervently wish that the original author had taken three minutes to document that instead. _Especially_ when that original author was me. 😏

@Challseus Год назад

I really, really appreciate the production values of your videos. Always love seeing your code on screen. It’s crisp, lol. Keep it up 💪🏾 Regarding the topic, I love it. I’m really trying to set some standards for documentation on our team, this is some good stuff

@ArjanCodes Год назад

Thanks for sharing!

@ThomasBakerH Год назад

Great video as always. I might have added unit tests here as a form of documentation. Unit tests can also have clear names, and their docstrings can comment on how edge cases are handled. If I'm coming back to code I wrote six months ago, it's the first place I go.

@Doppelwulf Год назад

I like more verbose docstrings on functions and methods because they appear in the mouseover in the IDE. That allows me to more easily see the parameters etc. without having to open the file containing the method or function.

@marioluizbernardinelli2659 Год назад

Arjan, this video is great! You are the guy! Thank you!

@ArjanCodes Год назад

Thank you, Mario!

@TomTrval Год назад

Thank you Arjan this is pretty good tutorial I like you always do quick reasoning about motivation behind each documentation fragment. My general rule of thumb for `comments`. Comment has to explain "WHY" the code is here, not "WHAT" this part of code doing. If I have to write WHAT the code does, it means I messed up naming or code structure.

@davidbohlin2305 Год назад

This is something I have been trying to get my team to do better. This is a very good into to what good code documentation should look like

@ArjanCodes Год назад

Thanks David!

@PhunkyBob Год назад

Thank you for your precious advices. I think I become a better developper with your videos.

@jobdenotter Год назад

Another suggestion for making your code more readable is adding units of measurement to the variable names. In this example, it would be nice if the parameter to the deposit and withdraw function would be called amount_in_cents or amount_in_euros etc.

@ecociudadesperu 24 дня назад

Wow!!...very good teacher, I hope it's enough motivation to learn Python 😊🐬

@ArjanCodes 18 дней назад

Glad to hear you liked the video!

@obsidiansiriusblackheart Год назад

Wow, whenever I watch your videos, I learn something. Better Comments, using now! Thanks

@ArjanCodes Год назад

Thank you!

@eltreum1 Год назад

You know its going to be a good day when you open a module and the line counter stretches to 6 digits, adds a horizontal scrollbar on your widescreen, and there is only one docstring at the top. '''Abandon all hopes ye who enters here.'''

@paulovictorespindola7496 6 месяцев назад

helpfull i was anxety about find some easy way to document my project, and i found here ^^

@ArjanCodes 6 месяцев назад

Glad it helped!

@user-mk3hi2ln8e 10 месяцев назад

Thanks for the video, it gives some great tips! I'd like to comment on some aspects (being a technical writer _and_ a developer) and would also like to share some of my experiences what I made from both roles: * Docstrings are awesome Yes, sometimes docstrings take more space than the actual documentation. If this is a public function or method, that shouldn't prevent us to write it. If the doc is autogenerated (like an API), the doc should be complete. * Focus on your target group(s). If your doc is autogenerated, it is probably more focused on developers. But depending on your project, developer docs are maybe not enough. Also take users and tutorials in mind. * Autogenerated API documentation isn't a replacement for user docs. It looks easy and it's tempting to get the impression, "I documented all functions and modules, so I have all documentation." This is the wrong approach. Depending on what you write in your docstring, a pure autogenerated API documentation listing only the functions and parameters is pretty useless. It doesn't tell you _how to use_ the project. We need flesh to the bones: some examples and context.

@shikotei1260 Год назад

super vidéo très utile et très attendue sur RU-vid

@marceloeduardobenencase5857 Год назад

Man, I wish I knew you when I started programming. Currently I work in a Brazilian Company that provides R&D services on Robotics and Computer Vision globe wide. We're great researchers, but terrible on writing quality code. I'll force everyone in the company to watch you!

@ArjanCodes Год назад

Wow! Thanks for sharing that and for your support!

@generalsnow8283 Год назад

Regarding the docstrings I think it really depends on the use case, if you are writing a code for a project like an API for an app frontend or a data pipeline or some other type of product then it doesn't really make sense to write a docstrings because as you said the main goal should be for the code to be as clean and structured as possible and that should be enough, because adding docstrings basically just duplicates the stuff you already do in natural language and in case of bugs it can lead to even harder debugging because you could potentially inspect the docstring and move on. However the use case where it is absolutely necessary is for example writing libraries, the user of the library has to know what is going on with the function and all the arugments passed to it and it doesn't really make sense for him to go in the implementation rather he will read the method docstring and that's it.

@maziarjamshidi4505 Год назад

Great tips! That would also be helpful if you make a video on how to write useful "git comments". Thanks!

@ArjanCodes Год назад

Noted!

@mohammadhosseinesfahani8417 11 месяцев назад

TNX, Nice

@airatvaliullin8420 Год назад

Came here from the Python Weekly :)

@user-ml5em9eo2e 11 месяцев назад

Thanks

@mikefochtman7164 Год назад

The industry shift towards 'self-documenting code', where the naming and coding style itself explains the goal of the code, has been a good thing (IMHO). There have been times where some 10-15 year old code works one way, but the comments never got updated to agree. Some maintainer along the way just couldn't be bothered to 'fix the comments'. And not to sound TOO MUCH like some old 'boomer', but yes, there is a ton of code out there that has to be maintained that is probably older than half of all comp-sci degrees awarded. lol A few times when good comments really help is when you find yourself employing some 'trick'. Some coders like to keep some 'trick' all secretive (like maybe 'bit-twidling' some float to extract a fraction or shift lower-case ASCII to upper). They get a bit smug and make statements like, "Well if you were a good programmer, you wouldn't need a comment to understand this." But adding a tiny comment to explain some obscure detail is the mark of a really good coder.

@jirkadolezal8127 Месяц назад

thank you

@ArjanCodes Месяц назад

Glad you enjoyed it!

@aidanheffernan652 Год назад

Outsourcing most of my documentation to LLMs

@OOD2021 4 месяца назад

I only make fully filled google style docstrings for my packages of the classes and functions that the package user is interacting with, and which I have documented using mkdocs. All other code will have a simple typehint and a short summary in the doc string.

@dpgwalter Год назад

About docstrings taking up too much space: It really depends on the style used, e.g. a section in numpy style takes at minimum 4 lines (title, -----, name, description) while in google style it's collapsed down to only two ("title:", "name: description")

@Alticroo Год назад

Just as I am writing docstrings and READMEs

@walis85300 Год назад

Is there any reason why you picked the mypy format for docstrings? Is it the one that you use?

@djangoheroes7012 Год назад

cool!

@abdelghafourfid8216 8 месяцев назад

What is the shortcut used for auto imports ?

@prashant4moni Год назад

you ar best

@ArjanCodes Год назад

Thank you so much!

@StevenMartinGuitar Год назад

Re: Documentation taking up more space than code and making it harder to see. Is there not a way to auto fold all docs?

@spaderkungskuk Год назад

Is there a summary function for Better comments? Even if colored, they are still hidden within the code.

@chudchadanstud 10 месяцев назад

Sometimes thise comments that explains simple code are helpful. Because they're plain English (or your language) you can quickly get the gist of what's happening as if your reading a book. I will then look at the code if I want further details.

@edgeeffect 9 месяцев назад

If you need to explain your code in plain English, this *may* be an indication that the code is bad and needs rewriting.

@chudchadanstud 9 месяцев назад

@@edgeeffect No. Stop this sheepish nonsense. Perfect readable code doesn't exist. Go look at any of the Rust, Python, C++, C#, etc. source code. Sometimes your code is doing something complex and you dont need indentation, syntax, and error handling to get in the way. You just want to get to the meat and bones pretty quickly. Also you don't need to rewrite everything. Just been you don't understand it doesn't mean nobody understands it.

@CrYpt001 Год назад

I would love to build some visual documentation tool or something .

@airatvaliullin8420 Год назад

When giving a typehint for an argument of the same type as the self class, instead of Self one can use "": "BankAccount" in this case. This way you don't need to include anything.

@pablogonzalez7959 Год назад

I have two problems with typehints. First, imagine I have a class defined in a file and in another file I have a function that takes as a parameter an instance of that class. To use typehints I import the class in the function file and because I need the function in the class file I also import the function file in the class. This is an obvious problem because I do circular imports. They way of solving this is putting the function inside the class file but I dont know if this is a good practice or not (I mean it should be the good practice if you can't use typehints without an import, that's really my question, can you use type hints without an import?) The other problem is with typehints and numpy, I also like to have an strict type checker but with numpy I don't know how to use it, sometimes I have used the ArrayLike type but the type checker goes nuts.

@Sinbad510 11 месяцев назад

I could be wrong, but I think if you surround the typehint in quotes ("), then it forward declares it and you don't need the import, e.g. -> "ObjectFromOtherFile". Also for type hinting numpy arrays you can use np.ndarray

@haniefedwards9764 7 месяцев назад

I am struggling to include a table from an excel .xlsx file in my sphiinx documentation. If anyone has done this, I would appreciate some pointers.

@Skrattoune 11 месяцев назад

I've tried to generate the documentation of my django project with mkdocstrings. After testing a few things and exploring further, I managed to get the yml file working with django. Then I installed with the python-legacy handler ... and It more or less works ... until ModelForms are discovered ... and then it crashes ! When I'm trying the same with the new python handler whcich does not execute the code ... I end up with empty documentation pages (official documentation say that the experimental new handler is not yet compatible with Django) ... Could anybody tell me how to generate docstring documentation on a Django app? ... or how could I bypass specific functions, classes or modules ?

@jfragoso95 Год назад

I think that Sphinx could also be a great way to improve our documentation. I suggest to include this tool maybe in a part 2 or in an extension of this video. Thanks so much for making so interesting and complementary topics for the Python Community! 🐍 💻

@ArjanCodes Год назад

Thank you!

@spammich1120 Год назад

I dont like the direction your content on this channel is going recently. I started watching your content because I felt you were discussing more intermediate to advanced topics, did code reviews in that way and so. Your strength lies - imho - in breaking down these topics in a simple and concise way that's easy to understand for everyone. Your recent posts however are really beginner tutorials of which there are so many in youtube. You are still doing it in your usual great way, but I don't really see a reason anymore to watch any of your content if you are going to be just one of the many python beginner youtubers. Your channel, your choice, of course. So make of that what you will!

@therollingambit5222 Год назад

This video is very informative for me and it's good he has a mixture of beginner to intermediate/advanced topics that cater to everyone. I don't see anyone else talk about some of the points he brought up tbh

@ArjanCodes Год назад

Some of my recent coding videos are about building a tool on top of the OpenAI API, functions vs classes, pandas/pandera for data validation, sql query builders vs ORMs. I'm surprised you consider these topics beginner-level.

@RazeVX Год назад

the docstring part is a basic feature of pycharm what overall is a create ide for python imao

@YossiZinger Год назад

Best way to document your code is with tests. They define what the code does and they are always up-to-date

@ThatOpinionIsWrong Год назад

I've used to put docstrings on everything that was more than few lines long but then I've started applying clean code concepts and my code is self documented, I only ever use the single line # comments nowadays.

@bonquaviusdingle5720 Год назад

Do a Mojo video 👍

@DanielWeikert Год назад

I have the issue that certain shortcuts in vs code do not work (I assume the issue is that a shortcut is used multiple times by various extensions so vs code does not know what to do) Can you show how to handle this in a video? br

@Ultrajamz Год назад

Sadly employees feel punished for writing documentation that is too good, because it becomes an employers guide for replacing you with a lower paid person.

@TheRich107 Год назад

If you make yourself too irreplaceable then you make it harder to get promoted.

@astronemir Год назад

If you do great work to a level that you are replaceable at any moment, you are irreplaceably valuable. Any project, any initiative, any codebase will want to have you

@tommybrecher7742 Год назад

You are right, I do feel punished for having my PR fail because I didn't write a docstring on an init method with 2-3 vars that are fully annotated. Write simple, explanatory code and document what's needed, comments are going to get dated anyway and become more confusing to users. That's just reality.

@RolandHesz 11 месяцев назад

Based on personal experience being the only one who knows the details of an "in house developed" software is no guarantee against layoffs, but it will make sure that you will have trouble going on a hokiday without being disturbed.

@dinoscheidt 10 месяцев назад

@OP If you are in an environment like that, and don‘t get fired for not enabling knowledge transfer, you are part of the problem and did not find a solution. Because you don’t get promoted or even fired since the next guy to you is doing the same thing. Try to set an example, if it doesn’t work get out of these places or be fine in being caught in a vicious cycle of despair reinforcing your own pain.

@user572d 11 месяцев назад

The code tells you how, comments tell you why.

@joannloos17 Год назад

I started programming in the 80’s. I did a lot of code archeology. The running joke about documentation was if the code was hard to write it should be hard to read