I follow the Pep 8.0 standard when doing comments in Python. I follow the same standard for the most part in SQL.
I also mix this with the Google Python Style Guide to even further enhance my code and comments.
So, does this help in the long run when it comes to code comments? Sure. When you start getting into complex projects, I've often have forgotten what things do. Take the below code example with a simplistic algorithm that's written in such a way that humans can easily get confused.
def array_query(s, t, i, j):
if t == 1:
s[:0] = s[i-1:j]
del(s[i+(j-i):j+(j-i+1)])
elif t == 2:
s += s[i-1:j]
del(s[i-1:j])
return s
When I wrote this code with a Google engineer helping me out, it's pretty fresh in my mind. But, going back to it over a long period of time can be hard to understand what's going on at first glance. For new eyes on the project, it can also be very confusing on what's going on unless you're just that good. You toss in comments, then at least you get an idea that hey, this is simply taking an array of objects and just shifting them to the front or back of the array based on input.
def array_query(s, t, i, j):
""" A simple algorithm to shift a range of positions to front or back of the array.
Type 1 Query that modifies the given array by removing elements from i to j and adding them to the front.
Type 2 Query that modifies the given array by removing elements from i to j and adding them to the back.
:param s: The query string we are working with
:param t: Query Type. 1 moves to front of array, 2 to the back
:param i: N starting number for range
:param j: N ending number for range
:return : New array with the chopped number ranges specified from i and j.
"""
if t == 1:
s[:0] = s[i-1:j]
del(s[i+(j-i):j+(j-i+1)])
elif t == 2:
s += s[i-1:j]
del(s[i-1:j])
return s
The style guides, especially the Google Python Style Guide help a lot in helping define what your SHOULD do in terms of comments. For example, when it comes to all your functions and classes, adding your typical header/doc strings to the code to help you define what is going on. What the purpose is, what params you are passing, what you are returning, defining some examples of usage and even what error catches you have defined.
I follow the same in SQL with the help of SQL Prompt. I put headers on every stored procedure that defines the purpose, examples, and so forth with the history of authors who last touched it. The same is true for each major SQL statement with it's own small header to define what's going on. I think in the long run, it helps a great deal with getting a quick download of large and sometimes complex code.
Here is my final submission for the above code. This would be further enhanced with an example input and output.
def array_query(s, t, i, j):
""" A simple algorithm to shift a range of positions to front or back of the array.
Type 1 Query that modifies the given array by removing elements from i to j and adding them to the front.
Type 2 Query that modifies the given array by removing elements from i to j and adding them to the back.
:param s: The query string we are working with
:param t: Query Type. 1 moves to front of array, 2 to the back
:param i: N starting number for range
:param j: N ending number for range
:return : New array with the chopped number ranges specified from i and j.
"""
if t == 1:
s[:0] = s[i-1:j]
del(s[i+(j-i):j+(j-i+1)])
elif t == 2:
s += s[i-1:j]
del(s[i-1:j])
return s
if __name__ == "__main__":
input_size = map(int, raw_input().split()) # Array size, Total Queries
source_array = map(int, raw_input().split()) # Input array
for case in range(0, input_size[1]):
test_case = map(int, raw_input().split())
array_query(source_array, # a[ ] = Input Array
test_case[0], # q[0] = Query type
test_case[1], # q[1] = i range (Min)
test_case[2]) # q[2] = j range (Max)
print abs(source_array[0] - source_array[input_size[0] - 1])
print ' '.join(map(str, source_array))