Functions, naming conventions in Python

[Jarvis323]

I'm a minimal commenter as well, but agree with Ibix. You should write comments when you expect other people who will read the code won't understand something.

The problem with comments is that you can write anything in a comment and the code will compile. Each comment introduces a long term vulnerability since it will need to be updated and synchronized with the code as it changes. The more comments you have, the more work that becomes, and the less likely a person is to be diligent in updating them. In general, you cannot rely on them to be accurate. And, if there are too many mundane comments, the reader may just stop reading them and then miss the important ones (like the boy who cried wolf).

 

[Mark44]

Programming can be a messy struggle, especially if you are working in other people's code. Comments can help a lot.

The bulk of time in the software development life cycle (SDLC) is spent on maintenance, usually done by someone other than the original developer, who is likely off in another job, perhaps in a different company. Code steps that seemed trivial to the original developer might not be so to someone else who is tasked with fixing bugs that the code generated. Comments can help this person, especially if they have been kept up to date and are correct explanations of what the code is doing.

 

[FactChecker]

I don't know what other people have experienced, but my experience is that there are far more cases of too little commenting than too much, especially from beginning programmers.

 

[Vanadium 50]

You should write comments when you expect other people who will read the code won't understand something.

Including Future You.