Top 7 Ways To Document Your Code

as a developer you supposed to write code but as you grow in your career there's a need to read the code and understand it not only this you supposed to read understand and fix the bugs in the code written by other developers documentation is really important but I'm not saying you write ly tens of pages of documentation in fact there's a simple and more effective way to write the documentation and this is exactly what I'm going to share in this video two have seven ways to document your code and the first one is self-documenting code so documenting code is all about writing your code in a way that it explains itself this means using clear descriptive name for your variables functions and classes for example instead of naming a variable X you could name it total sales and this makes it obvious what exactly the variable is and what exactly it's holding and another aspect of selft documenting code is structuring your code in a logic way group related functions classes together and use many directory and file names after Al follow common coding conventions and best practices this help others to quickly understand your code without any extra explanation overall the goal is to make your code base easy to understand easy to maintain even for those developers who never work on the project and this single practice reduce the need for extra comments and documentation making maintenance easier and faster but at the same time commments are also important at many different stages and this leads towards to Second common way to document your code which is commments commments are powerful way to document your code but you have to use them wisely a good command explain the why behind the code not just the what and this helps other developer to understand the context and reasoning behind the code for example instead of saying calculate the total you might write calculate the total sales for the month to determine the bonus this provides more context and makes the code easier to understand make sure the real goal of writing commands to add Clarity and value and not the Clutter and the next one is unit tests unit tests are important for ensuring your code work properly but they just serve one more purpose documentation each unit Test shows how a particular function or method is expected to behave this is incredibly useful for other developers who are trying to understand what exactly your code is doing for example a test for a calculate total function might shows that it takes a list of numbers and return their sum this makes it clear how the function should be used and what kind of data it expecting so your test are not only prove the readability of your code but also serve as a documentation for current and future developers and now let's talk about the next Point inline documentation inline documentation refer to commments placed directly in the code to explain specific lines or sections this is done using do strings especially in the languages like python do string are special commands that describe the purpose of function or class its parameters and the return values for example in Python you might have seen something like this for example this drop string provides a clear explanation of what the function does what input it expects and what it returns this makes it easier for other developers to understand and use the functions without having read through the entire code inine documentation is not limited to functions you can use it for classes modules and even individual lines of complex logic it's also an excellent way to make your code more maintainable and more user friendly and the next one in my list is my favorite one get commit messages need commit messages are a really an important part of documenting your code changes they provide context and reasoning where we change helping others to understand why a change was made a good commit message is descriptive and clear it provides to other developers what the change was made and why the change was made for example instead of writing fixed book you might write fixed book causing incorrect total calculation in sales report it provide a clear context to the projects history not only to the existing developer but also to the Future developers and the next one is readme file readme file is an important aspect of any project it provide the overview of the project how to set up how to install how to run how to debug and much more a well written read me is the first thing a new developer or user will look at so it's important to make it clear and informative and here are some key ele ments which can be part of re project title and description installation instructions user guide features contributing contact information and more and in fact GitHub does offer an option to add a r file when you create a new repost the VCF file serve as the front door to your project helping others quickly knows its purpose and how to get started because R me file is a part of reposter so it's always relevant to the project and the next one is document tools there are many documentation tools available in the market but first let me highlight what exactly these tools are in simple words documentation tools read your code looking for commments annotation and other information this might include description of function classes parameters and return values then they convert this organized information into more readable format like web pages PDFs or Mark files some popular tools include gs do for JavaScript phix for python for cop and ESP do doc effects and Sanda and the list goes on but I hope you get the idea so this documentation tool will make sense if coding is easy for you if coding is hard then these tools will not help you to make coding easier I have another video for you coding was hard until learn these three things I hope it helps and thank you for watching

Channel: Rajeev Bera

Views: 84

Keywords: learn to code, coding tutorials, how to learn programming

Id: rM-At77RMh0

Length: 5min 49sec (349 seconds)

Published: Wed Jun 12 2024