if ( ((blah < 0 ) and (grr > 234)) \ or ((foo == 3456) and (grr <= 4444)) \ or ((blah > 10) and (grr == 3333)) \ ): print("this crazy condition is true") print("and my code is really easy to read because") print("I didn't wrap lines!") else: print("this crazy condition is false")Here is an example of breaking up a long comment into multiple lines:
x = foo(x); # compute the value of the next prime number # that is larger than x (foo is a really bad # choice for this function's name)The easiest way to make sure you are not adding lines longer than 80 characters wide is to always work inside a window that is exactly 80 characters wide. If your line starts wrapping around to the next line, its too long.
File Comments: Every .py file should have a high-level comment at the top describing the file's contents, and should include your name(s) and the date.
Function Comments: Every function should have a comment describing:
My advice on writing function comments: write the function's comment first, then write the function code. For complicated functions, having a comment that lists the steps of the algorithm, will help you
When commenting stick to a particular style. For example:
def approxPi(n): """ computes an approximation of pi using: pi/6 = 1/2 + (1/2 x 3/4) 1/5 (1/2)^3 + (1/2 x 3/4 x 5/6) 1/7 (1/2)^5 + n: number of terms in the series to sum returns: the approximate value of pi obtained by summing the first n terms in the above series, returns zero on error (if n is non-positive) """ def squareTheBiggest(n1, n2): """ Computes the square of the largest of its two input values n1: one real value n2: the other real value returns: the square of the larger of n1 and n2 """In-line Comments: Any complicated, tricky, or ugly code sequences in the function body should contain in-line comments describing what it does (here is where using good function and variable names can save you from having to add comments).
Inline comments are important around complicated parts of your code, but it is important to not go nuts here; over-commenting your code can be as bad as under-commenting it. Avoid commenting the obvious. Your choice of good function and variable names should make much of your code readable. For example, a comment like the following is unnecessary as it adds no information that is not already obvious from the C code itself, and it can obscure the truley important comments in your code:
# this is a bad in-line comment: x = x + 1 # increment the value of x
Class Comments: Every Class should have a high-level comment describing what it does, and each of its method functions should have a comments similar to those of regular functions.