Post Deleted by Community
Post Locked by Community
Post Migrated Away to programmers.stackexchange.com by David Richerby, Rick Decker, Gilles
Post Closed as "off-topic" by David Richerby, Rick Decker, Gilles
1

# How much commenting is better for coding?

I don't formally have Computer Science education. This means I did not study a lot of these things at university. But now I work in programming and write a reasonable amount of code for work. Naturally programming means that I also have to document and comment my code.

The problem I seem to be having is deciding between two schools of thoughts:

1) Comment the hell out of your code e.g.

unsigned int subtractor (int subtractee, int subtractor)
{ /*
- This function is a subractor and is used to subtract one integer from another.
- In other words the case here is subtractee - subtractor.
- Please ensure that the subractee is larger then the subtractor because this
function will have undefined behaviour for negative answers */
(The code here...)

}


2) The code that explains itself let it be (no need to comment) like in this example. Just use good meaningful names.

Perhaps this example code makes one think that option 2) is better, but programmers with experience on large projects know that sometimes only meaningful names are not good enough. I know some commenting at appropriate places is a good practice but is it also a good idea to comment like in 1) to describe almost all major methods/functions?

The reason I ask is that a senior colleague at work told me to do as in 1) but now I am reading Clean Code by Robert C. Martin and it actually pretty simply states that 1) is a bad practice.