A look into Python: Math module & Commenting Style
Intro
By default, Python does not has a comprehensive mathematical functions when you first open the program. It is lacking in common mathematical functions like square root, pi numbers, tan,cos,sin and etc. Nevertheless, this issue is not a big problem as we can import a module named math into Python.
Importing a module
To import the math module, all we have to do is to just write import math in IDLE, or in any .py file, for that matter and just press Enter or run the .py file. Once you've done that, you will notice that nothing actually happens. What's happening is that, Python has added a directory called math into its current library. To see where is the math module, you can type dir() and press Enter. To understand this better, I have included here, 2 images from IDLE that shows the difference between before importing the math module and after the math module is imported.
The directories that are available prior to importing the math module
The directories that are available after importing the math module
Notice that there is an additional directory called 'math' that appeared when math module is imported. In order to know the mathematical functions that exist within the math module, all you have to do is type dir(math) and press Enter. (refer below)
These are all the built-in functions within the math module. At this moment, you might wonder what each of this function does. Worry no more, all you gotta do is type help, followed by parentheses and the function that you need to understand. For example, if you want to know more about the sqrt function within the math module, you can type help(math.sqrt) and Python will give the description on it. To better demonstrate this, I have included the screenshot from Python as below:
As it turns out, the function sqrt returns the square root of a number. Notice that you have to type the module's name followed by a dot & the function's name. This can be interpreted as saying that we are accessing sqrt function within a math module.
Now, lets use this in a function. Let say we want to compute the area and circumference of a circle. From our math class back in school days, area of a circle is equal to pi(D^2)/4 while circumference of a circle is equal to pi*D. Since pi is not included by default in Python, we will need to import math module in order to use pi. The following image shows how we import math module & using pi within a function.
Referring to the above example, when the diameter is 10 meter, the area will be 78.539 m & the circumference will be 31.415 m. Quite simple right? Basically, we just have to import the module and call the function within the module in order to use it.
Commenting the Codes
There is one important thing when it comes to coding other than the code itself, which is the commenting part. Writing comments when coding can be regarded as a way to document our code. Commenting can be useful for several purposes such as:
- Ease for human readability and understanding. This will come in handy when you plan to share the codes to other people.
- Provide explanation on what does the code supposed to do.
- Provide explanation on how to use the code.
In Python, there are 2 commenting styles, which are:
- Single line comment. (# style)
- Multiple lines comment. (triple-quote style)
The single line comment uses hash # character, followed by user's comment. This type of comment is only valid for 1 line. If more than 1 line is required to be commented, each of this line needs to be started with #. Example of this comment is as followed:
The second and more common style of comment is called triple-quote comments. It is called tripe-quote because it started with """ and ends with """ with the comments written between them. We can comment as many lines that we want as long the comments lie between the triple-quotes. An example of this is shown as below:
As you can see, commenting can be done in multiple lines as long they are within the tripe-quotes.
Choosing Commenting Style
OK, now since we have 2 commenting styles, which one should we use?
Personally, i would choose both styles; depending on the situation. If the comment is just for the programmer to refer, then the # style is fine to choose. This is the case because the # style comment will be completely ignored by Python and can only be referred if the code is editable. For the triple-quote comment, it is not only useful for the programmer but also the user. This is because the triple-quote comment becomes part of the function. We can actually type help(name_of_function) and see the comments that lies within the function. Referring to our last example, lets write help(Circumference_Circle) and lets see the comment in action. (refer below)
As you can see, the comments that we have written in the code is displayed with the help function, which is very helpful for user to refer. Again, take note that this will not work for single style # comment.
That's all from me now. Do let me know what do think on this post and if there is any suggestion for future topics.
Cheers,