View Single Post
Old 2019-11-04, 00:37   #5
Dylan14
 
Dylan14's Avatar
 
"Dylan"
Mar 2017

24A16 Posts
Default Comments

Perhaps the most useful thing of good code is well commented code. After all, without them, we would just have to rely on reading the source code and hope that we understand what is going on in the code. Of course, the comments should be about the code (or, at the very least, clean, without obscenities. I.e., don't be like Ponytail in 1790!)
So what do I mean by well commented code? I say that code is "well commented" if it satisfies the following:
1. Each piece of a script or program is commented.
2. The comments are relevant and explain clearly what is going on at that point. Comments need not be sentences or regular statements (sometimes a question is best).
3. Comments are marked in the right place within the code (meaning, if you have a function withing the code that takes a function and then plots it, you would not mark a comment saying to plot the function when you are evaluating the function at multiple points).
4. (Optional) If a piece of code goes through multiple iterations, it may be worth commenting what versions and changes have gone on over time.
The last point is optional since a) version control via svn or git keeps track of changes in the code, and b) some authors may include a file called changes.txt which says what has changed.
Now how does one do comments in Python. This is very simple. For a single line comment, one can preface the line with the following character:


Code:
#
Once this character is placed in a line, the rest of the line is not evaluated when the interpreter is run. As an example, run a script with the following:


Code:
#This comment comes from mersenneforum's Python guide.
(nothing should come out and you should return to the prompt).
The # character can also come anywhere in the line and everything after that is treated as a comment. Such a comment is an inline comment. An example can be found in my mlucas compilation script, where we check to see if the error log is empty before we go and and link:
Code:
if os.stat("erroravx512.log").st_size == 0: #grep came up empty
Now what about multiline comments?
Unlike, say, Java, you can't just do something like


Code:
/* Some comments need
more than one line,
like this one */
Or like this:


Code:
#Some comments need
more than one line,
like this one
(the second code example will ignore the first line, but the code will error out with a syntax error when it hits the second line). So how do we do a multi-line comment? We have two options:
1. For each line, we preface the line with a # character.
2. Encase the comment in triple quotes.


Applying this to the last code block, the following are equivalent(*):
Code:
#Some comments need
#more than one line,
#like this one
Code:
"""
Some comments need
more than one line,
like this one
"""
(*) Care has to be taken with the triple quotes. In actuality this is a string that isn't referenced by anything, so it doesn't do anything in the program. Also, if you use this construct inside a function, then the object becomes a docstring (documentation string) associated with that function. If in doubt, just use the # character!

Last fiddled with by Dylan14 on 2019-11-06 at 21:01 Reason: initial draft
Dylan14 is offline