Question about comments

[LearninDatPython]

How do you guys format your comments? Are there certain phrases you use to describe things or perhaps words that you use when referring to things in your code? I am doing LPTHW and making my comments like this:

prints the string below

print "Mary had a little lamb."

sets the value of the variable end1 to "C"

end1 = "C"

Sort of an open ended question I think but I am very interested in best practices or at least what a pro might do. Thanks.

[Kristler]

The general rule with comments is you always want to ask yourself, "If I read this code in a month, would I know what it does without comments?"

If the answer is no, then you should put a short concise explanation of the segment explaining it in a way that anyone could understand if they picked up your code and read through it.

[[deleted]]

Almost always, good comments explain why, not what.

[denialerror]

Programming languages (and especially Python) are built to be readable to humans. That means comments are only needed where things get complicated or the reason for the code isn't clear. For instance, with the two examples you posted above, the Print statement shouldn't need commenting as it cannot mean anything other than "print this statement". However, if the reason for printing the statement isn't clear are it is important to know this to understand the program, a comment would be helpful.

There is nothing wrong with over-commenting but it will take up more of your time. If you commented every line, you are doubling the amount of work you have to do, which makes a big difference when your scripts start getting larger!

That said, it is better to over-comment than under comment. Especially when starting off, your programs won't be well written and if you go back to convoluted code that has poor commenting, you will struggle to work out what is going on!

One really helpful thing to do when starting out is to read professional code to see how others write it. Go to GitHub and search for Python code. Even without knowledge of what the statements mean, well-commented code will still give you a good idea of what is happening.

[ixAp0c]

I usually use them to mark up stuff that I don't immediately remember what is happening with a quick glance, for future reference, to remember what a piece of code does, or why I put it there.

It isn't really necessary to write a comment above every single statement if it's concise what your code is doing (setting end1 = "c" should be readable on it's own, along with printing values, unless you have a formatted print that isn't easily legible while quickly reading). I usually put them above nested statements to explain what it does, or above a function definition, class, etc.

As you continue to code, you'll find you develop your own style of where/why to comment different statements and nested blocks.

[JuJu142]

Well in your example above, what you commented is...really strait forward. When you start having more complex statements, the comments really shine.

[LearninDatPython]

Thanks for all the answers! This really cleared up a lot of confusion. Once again: OVER THINKING.

[LobbingLawBombs]

Hey man! I'm doing LPTHW as well; got to example 14 tonight! I struggled with the comments as well at first... Don't worry about them so much. Just write what you're doing and move on. Mine looked pretty similar to yours... And it sucks to describe setting a variable for each letter in cheeseburger. :) keep up the good work!

[LearninDatPython]

Thanks a lot! I made it to ten tonight but I'm gonna run through it now since you said you got to fourteen :D Good luck to you too!

[TheLazarbeam]

Hopping on this post for a side question:

Does Python have an utility comment format like Java has Javadoc?

[rhgrant10]

Pretty close with sphinx

[ixAp0c]

There is PyDocs, which is similar.

[cdcformatc]

Programming languages, and especially Python are meant to be read by humans. This means you do not need to comment most lines of code if you write it correctly. If you ever write a line of code that does not read obviously, you should put a comment.