Documenting vs Commenting Code

00:00 Welcome to Part 3 of the Real Python tutorial for Documenting Your Python Code: Documenting versus Commenting. Before beginning to document your code, it is important to first distinguish the differences between documenting and commenting. Generally speaking, comments describe your code for fellow developers. They’re intended to aid those that are further developing and maintaining the code. Together with well-written code, comments help guide the reader to better understanding the code, as well as its intended purpose and design. “Code tells you how; Comments tell you why.” Jeff Atwood, a.k.a. Coding Horror. Documenting code is describing its use and functionality to your users.

00:42 It may aid in the development process, however the main intended audience are potential and actual users of the code.

00:49 Now let’s take a look at when you should comment your code and just how to do that. Creating comments in Python is done by starting the line with the pound sign (#), or hash, depending on what you’re more familiar with.

01:00 They should be brief and no more than a few sentences. Now, check out this sample onscreen. As you can see, there is a comment saying # a simple comment preceding a simple print statement.

01:12 You can see the hash or the pound, if you will, just here, and you can see that it’s colored differently as well, indicating syntactically that it’s a comment and not a function or anything else. Now, according to PEP 8, which is a standard guidelines for laying out Python code, comments should not be longer than 72 characters, and this should remain true even if your project changes the maximum line length to be greater than the recommended 80. If a comment is going to be longer than the character limit, splitting it up over multiple lines is appropriate. If you look here, you can see the comment going across two lines, both lines starting with the hash key or pound, if you will.

01:56 Now, why should you comment? Commenting your code serves multiple purposes. These include planning and reviewing new segments of code, as it may first be appropriate to use comments as a way to outline the purpose and function of that section of code.

02:11 Just be sure that you delete the comment once the segment has been completed. You see an example just here. Code description, explaining the intent of specific sections of code. Again, see an example just here. # Attempt a connection based on previous settings. If unsuccessful, # prompt user for new settings. Short, sweet, to the point.

02:34 Algorithmic description. Using comments are useful in this case to explain how the algorithm works or how it has been implemented within the code. Describing why a certain approach over a different approach was taken may also be appropriate.

02:49 The example here shows that, # Using quick sort for performance gains. It tells you the method you’re using and why you’re using it. And finally, tagging.

02:59 This is a convenient way to label certain sections of code where known issues lie, or where improvements can be made. Some examples are # BUG, # FIXME, and # TODO.

03:11 Avoid overly long comments as often as possible. They should be brief and concise.

03:17 The following four essential rules, as suggested by Jeff Atwood, should be followed. Keep comments as close as possible to the code that they describe. When comments are not near the code they are describing, that can be frustrating to the reader and missed when updates are made down the track. Don’t use complex formatting such as tables or ASCII figures.

03:36 Complex formatting can be difficult to maintain over time and can also cause a distraction to the reader. Don’t include redundant information. Assume that the reader has a grasp of basic programming principles and coding syntax. And finally, design your code to comment itself.

03:53 The easiest way to understand code is by reading it. When your code is designed using clear, easy-to-understand concepts, the reader will be able to quickly conceptualize your intent.

04:03 Remember that comments are intended to give the reader help guiding themselves through understanding the purpose and design of the software. Now, one final aspect of commenting is type hinting. Type hinting was added to Python in version 3.5.

04:19 It’s an additional form to help readers of your code, and takes rule number four, mentioned previously, to the next level. It allows the developer to design and explain portions of their code without commenting in the traditional way.

04:32 Let’s take a look at an example. By examining the type hinting in this example, you can see immediately that the function expects the input name to be of type string, or str, just here.

04:45 You can also tell that the expected output of the function will also be of type str, denoted by the arrow or the dash greater than sign (->), which looks like an arrow, and str.

04:56 Keep in mind, though, that by using type hinting, you may end up creating extra work when it comes to creating or updating project documentation. There’s a very good video tutorial by Dan Bader available on the Real Python website that further explains type hinting and checking. However, our next video will introduce documenting your Python code using docstrings.

05:16 Hopefully, I’ll see you there!