4 ms·
//Insert new customer into database _db.Insert(newCustomer); The number of times I've had to point out how incredibly pointless comments like this are in cod
by jaywalk 6y ago
//Insert new customer into database
_db.Insert(newCustomer);
The number of times I've had to point out how incredibly pointless comments like this are in code reviews is far too high. As is the number of times I've had to point it out to the same developer.
- pjc50 6y agoWorse is //Insert new customer into database _db.Insert(oldCustomer); As a reaction to this, I used to work somewhere that had a zero-comment policy. If you wanted to describe something you had to do it in the function and variable names. Overreaction in the other direction.
- gregfjohnson 6y agoAbsolutely agree. I had a similar experience. 30-character camel case names are no substitute for a well-written comment. What I've found works well is to view a comment as the topic sentence of a paragraph. For each section of code that can be reasoned about as a unit, set it off with white space above and below as paragraphs are set off in text, and give it a topic sentence explaining the intention. If there are difficult, delicate, or subtle aspects of the code, be kind to your reader and explain them.
- godshatter 6y agoI get that, but if there is a comment above each portion of the code with a short description of what they are attempting to do, then I don't mind that some of them are trivial. You can read the (hopefully syntax-highlighted) comments as a list of steps in the function. Also, maybe that was a large block of code that was replaced later with a function call. Or maybe the code used to validate things about the customer used to be there before the function call and now that's all been wrapped into the called function.