Python For Beginners

Python For Beginners

Commenting and documentation in Python

Long story short: In the first lesson we coded our first Python program. Then in the second lesson we broke it intentionally and fixed it again. Finally, we want to document it.

Some vocabulary:

  • comment – code which will not be executed (it is still in our program, but compiler will ignore it)
  • inline comment – comment which is commenting only one line
  • comment block – comment which is commenting multiple lines of code
  • doc-block – comment which is actually a documentation (usually contains description of function, methods, authors, etc.)
  • Code smell – This is a programming jargon, which usually means that there are too much comments. In this case, it is suspected that code is not good, so the comments are there to (like a deodorant) to improve a bad smell of rotten code.

Disclaimer: Throughout this course, examples will have lots of comments (even where something is obvious). Reason for this is to make them understandable for learning purposes. In a production, lots of these comments would be excluded. Furthermore, lots of approaches and oversimplified examples would never be used in a production code (… or would they…).

 

Ok, lets put some comments (documentation) in our code.

We will take the example from the previous lesson and make it look like this.

Quick reminder, we are using Online Python compiler – https://www.onlinegdb.com/online_python_compiler

Note: As you can see, this time you have only screenshot (no code example), which means you will have to type it (no copy paste this time).

 

Python comments example
Python comments example

 

Single line comment

  • To make a single line comment, we write # at the beginning of a code line. Example on line 6.
  • If we put a # somewhere in the middle of the line, then only part of that line will be commented (right part of the line). Examples on lines 10, 12 and 13.

Comment block

  • Triple quotes ”’ are used to make a comment block (multiple lines of code which are commented).
  • Comment block is usually used to give us some information about code (task, author, date, etc.). Example lines 1-4.
  • Comment block can also be used to make part of the code ‘inactive’. Meaning, code will still remain, but it won’t be executed. Example lines 17-20.

 

 

 

Leave a Comment