How would a professional comment this code?
The first thing I do when faced with new code is delete all the comments, without reading them.
The most important part is giving things good names. As someone pointed out, `print_nth_prime' would have been a better name for your function. Even better, make the function return the n-th prime instead of printing it, and then call it `compute_nth_prime'. The code that calls it can decide whether to print the result or do something else with it. Code that computes things should not do I/O and vice versa.
The example of finding the n-th prime is too much of a toy to show you an effective use of comments. I'll just tell you what I normally do. There are basically three types of comments I write:
* A general comment describing a file, a class or a function. I only do this when the name of the class or function doesn't tell you everything you need to know about it. This type of comment is particularly important if there are non-trivial design decisions that the reader of the code might need to be aware of.
* A very brief comment describing what the next few lines of code do. A person that is looking for a particular part of the code should be able to quickly skip through the sections by just reading these comments.
* An explanation of a particularly obscure line of code (anything with a magic number in it, for instance).
The example of finding the n-th prime is too much of a toy to show you an effective use of comments. I'll just tell you what I normally do. There are basically three types of comments I write:
* A general comment describing a file, a class or a function. I only do this when the name of the class or function doesn't tell you everything you need to know about it. This type of comment is particularly important if there are non-trivial design decisions that the reader of the code might need to be aware of.
* A very brief comment describing what the next few lines of code do. A person that is looking for a particular part of the code should be able to quickly skip through the sections by just reading these comments.
* An explanation of a particularly obscure line of code (anything with a magic number in it, for instance).
Frankly, I think that putting comments after lines like that is horribly ugly. If you're going to do that, at the very least make the comments line up to the same tab.
This is better.
This is better.
def nth_prime(n):
# 2 is the first prime, start searching at 3
prime_list = [2]
number = 3
# search until we have n primes
while len(prime_list) < (n):
count = 0
#if number is divisible by i, increment count
for i in range(2,number):
if number % i == 0:
count = count + 1
#if there were no divisors, this is prime
if count == 0:
prime_list.append(number)
number = number + 1
print prime_list[-1]
I only comment for myself, like "TODO: .....", "FIXME: ...", "Dunno why the fuck this works" etc
Looking at this my new rule of thumb might be "commenting a single line of code is pointless and if you find it necessary to understand the line, you stuffed too much into that line".
I like comments above _blocks_ of code that describe what it does. Then I'd prefer if people just delete that comment and put the block into an appropriately named function. Or in short: I'm a fan of self documenting code.
Why? Because everyday I look at commented code where the comments and code don't match at all. Either the code was changed a dozen times without updating the comments or (even more comment) code was copy/pasted with all comments and only the code was adjusted. Also this:
Apparently programmers are just notoriously bad at keeping comments consistent and the older the code, the more confusing and misleading the comments will be. Solution: comment as little as possible and only where it is REALLY necessary (ie. the whole thing the code does really IS that complicated and can't be broken down).
I like comments above _blocks_ of code that describe what it does. Then I'd prefer if people just delete that comment and put the block into an appropriately named function. Or in short: I'm a fan of self documenting code.
Why? Because everyday I look at commented code where the comments and code don't match at all. Either the code was changed a dozen times without updating the comments or (even more comment) code was copy/pasted with all comments and only the code was adjusted. Also this:
//Function A
//long describtion of A and it's parameters and return codes
int FunctionA(...)
//Function A
//long describtion of A and it's parameters and return codes
int FunctionB(...)
//Function A
//long describtion of A and it's parameters and return codes
int FunctionC(...)
Apparently programmers are just notoriously bad at keeping comments consistent and the older the code, the more confusing and misleading the comments will be. Solution: comment as little as possible and only where it is REALLY necessary (ie. the whole thing the code does really IS that complicated and can't be broken down).
The vast majority of my comments are for doxygen, apart from those the only comments i use are for odd performance tweaks or "temporary" solutions. (of those the "temporary" solutions are the most common one)
Frankly, I think that putting comments after lines like that is horribly ugly. If you're going to do that, at the very least make the comments line up to the same tab.
This is better.
def nth_prime(n):
# 2 is the first prime, start searching at 3
prime_list = [2]
number = 3
# search until we have n primes
while len(prime_list) < (n):
count = 0
#if number is divisible by i, increment count
for i in range(2,number):
if number % i == 0:
count = count + 1
#if there were no divisors, this is prime
if count == 0:
prime_list.append(number)
number = number + 1
print prime_list[-1]
This.
In the project I am currently working on (36 files, 2675 lines of code) I have 0 comments :)
The purpose of comments is to convey information that isn't obvious from, or contained in, the code. Some might say that might indicate a problem with the code, but that's not always the case. The code contains what you're doing, but it doesn't contain the why. For example, if a line of code is part of a bugfix, it bloody better have a comment on it indicating this (and the bug reference number). Handling WM_ERASEBKGND by returning non-zero deserves a comment (and possibly even a link to the relevant MSDN article). If you do something in a way that looks stupid but you need to do it that way for compatibility with another program or a file format; that's a comment. If you're working around a known driver or OS problem - comment! If you're putting in a nasty ugly piece of code to resolve a confirmed performance bottleneck - you better have a comment explaining that.
In other words their target audience is yourself in 6 months time, or some future maintainer of your code. Because if you have anything in there that you or this person might potentially get a bad smell from in the future, and if you haven't explained why it's needed, then you're asking for trouble.
In other words their target audience is yourself in 6 months time, or some future maintainer of your code. Because if you have anything in there that you or this person might potentially get a bad smell from in the future, and if you haven't explained why it's needed, then you're asking for trouble.
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement
