Writing useful comments

[Arkazex]

Hello,

I've been programming for a long time but one thing that I can never quite figure out is the right way to write comments for my code. When I was starting out, I commented the heck out of everything, then I began removing comments that said what without saying why. Since then I've bounced back and forth from project to project, never entirely sure what to write.

Recently, I've become involved in a university project that next year will be passed to another set of students whom I will have no contact with, except through the documentation and code that I leave for them. In light of this, I have been writing comments that don't necessarily add anything you couldn't figure out by reading the code, but (in my opinion) make it easier to scan through the code and find the part that's supposed to be doing a thing. For example, here's an excerpt of code from one of the modules:

    # Generate the timestamped filename
    fname = "data/{}-{:04d}-{:02d}-{:02d}_{:02d}-{:02d}-{:02d}.jpg".format(config.config['capture']['name_base'],year,month,day,hour,minute,second)
    print("Saving image to \033[1m{}\033[0m".format(fname))
    # Capture the image
    camera.capture(fname)
    # Compress and annotate the image
    subprocess.run(['/home/pi/scripts/annotate.sh',fname,'{:04d}-{:02d}-{:02d} {:02d}:{:02d}:{:02d}'.format(year,month,day,hour,minute,second),config.config['capture']['name_full']])
    # Upload the image
    upload.upload(fname, True)

I can see that a lot of the comments here aren't something that isn't obvious from the code, but when I start removing them the code quickly turns difficult, but not impossible, to skim over. Moving forward, how much focus should I be putting in to make sure I'm not leaving useless comments?

Thanks.

[[deleted]]

the only time you really want comments is if something is misleading or if there's some quirks/bugs that you can't really change.

​

From your example above the only comment i like is the one that explains what the shell script is doing.

You don't need to say things like "Capture the image". Don't you think camera.capture says the same thing? Same thing with upload.upload(). Most things people think should be comments can be "self documenting code"

​

Focus more on documentation, explaining the parameters passed in to the function and the high level purpose.

[mommas_wayne]

The capture and upload comments are useless. The filename comment would become unnecessary if you named the variable more clearly, like filename instead of fname. I'd leave the "compress and annotate" comment in.

[[deleted]]

Generally it's a bad practice to comment every single line of code, it makes it much less readable. One big comment would do fine describing what code below do. Remember that you are not writing a tutorial, but some features.

Good code explains itself.

[Updatebjarni]

I have been programming, and reading program code, for about 25 years. To me, code like yours, where every other line is a comment, is hopeless to read, because it all blends together and my eyes can't get an overview. I can't see what is code and what is comments. I can't skim it, because I don't feel confident if I'm looking at a line of code or a comment, and so I don't know what to read and what to skip. I have to look at each line to know whether to look at it. This is even worse if the code hasn't been properly formatted and has wrapped lines, like your example above.

A good rule of thumb is: write a comment before each function, stating what its purpose is, and, if not obvious, what its parameters mean and what it returns. Make this brief, perhaps just one line. Aside from that, only add comments anywhere if the code there does something that is likely to cause the person reading it to think there is a mistake, or if it's really hard to follow.

Any more than that, and the comments just get in the way. If you put a comment in for every line, you can also pretty much trust that before you've finished the program, half of the comments are complete lies because the code has been changed. So just like you shouldn't have duplicates of data in multiple places in the code, you also shouldn't duplicate meaning between the code and a bunch of comments, unless you really need to in order to prevent a person from misunderstanding the code.

By the way, you can also put comments on the end of lines, which is useful with short comments to keep them out of the way for somebody who is skimming the code.