4 ms·

> Have you ever looked at a very large project(blue whale as I'd like to call them)? Yes, I have. And almost none of the comments matched the code. My new "hea

> Have you ever looked at a very large project(blue whale as I'd like to call them)? Yes, I have. And almost none of the comments matched the code. My new "head of engineering" ruled that almost all lines of code must have matching comments. I now frequently find people changing the code but not the comments during code review.

axegon_ 6y ago
Well that's an organizational problem. Personally when I do code review and I see a comment which is redundant or doesn't match the code, I immediately return the PR and tell the developer to fix it.
- seanwilson 6y ago
  - Comments aren't executed or covered by a test suite so it's much easier for mistakes in them to slip by. A comment like "Close the file when..." when it should say "Open the file when..." could easily slip by review or when the underlying code changes. Same with typos and wrong names. - When you're adapting existing code, misleadingly named variable names and function names are going to be quickly noticed and fixed as developers are forced to read them (unlike reams of external docs or big comments). If you name a function "close" instead of "open" by accident, someone is going to notice fast. > Well that's an organizational problem. Personally when I do code review and I see a comment which is redundant or doesn't match the code, I immediately return the PR and tell the developer to fix it. You can justify any misguided developer practice like this though. The question is "is this a worthwhile thing to spend time enforcing?" and not "is it possible to enforce?". Getting rid of manual checks is a good thing when you can too.
  - axegon_ 6y ago
    Things slip through inevitably but it's easy to correct them when you spot them eventually or am I missing something? That's what I do and that's what we've agreed upon with all developers and it's working flawlessly. This is turning into a philosophical question rather than a development one. What is worthwhile to begin with? As per Maslow's pyramid it's breathing, eating and drinking. I've had this argument with a former co-worker who was strictly against writing documentation and comments, precisely because it wasn't "worthwhile" and a "waste of time". "Right... Got anywhere to be right now or is your plan to finish your task till 11 and spend the rest of the day scrolling through facebook?" Common occurrence for that guy as a matter of fact. We've fought for years to take out the "we need that eod" to transition to long enough periods with realistic deadlines and plenty of time to spare for tests, documentation and so on. And it is something that we have now. It is proprietary software but the postgres example is perfectly valid - simply look at it.

axegon_ 6y ago

Well that's an organizational problem. Personally when I do code review and I see a comment which is redundant or doesn't match the code, I immediately return the PR and tell the developer to fix it.

seanwilson 6y ago
- Comments aren't executed or covered by a test suite so it's much easier for mistakes in them to slip by. A comment like "Close the file when..." when it should say "Open the file when..." could easily slip by review or when the underlying code changes. Same with typos and wrong names. - When you're adapting existing code, misleadingly named variable names and function names are going to be quickly noticed and fixed as developers are forced to read them (unlike reams of external docs or big comments). If you name a function "close" instead of "open" by accident, someone is going to notice fast. > Well that's an organizational problem. Personally when I do code review and I see a comment which is redundant or doesn't match the code, I immediately return the PR and tell the developer to fix it. You can justify any misguided developer practice like this though. The question is "is this a worthwhile thing to spend time enforcing?" and not "is it possible to enforce?". Getting rid of manual checks is a good thing when you can too.
- axegon_ 6y ago
  Things slip through inevitably but it's easy to correct them when you spot them eventually or am I missing something? That's what I do and that's what we've agreed upon with all developers and it's working flawlessly. This is turning into a philosophical question rather than a development one. What is worthwhile to begin with? As per Maslow's pyramid it's breathing, eating and drinking. I've had this argument with a former co-worker who was strictly against writing documentation and comments, precisely because it wasn't "worthwhile" and a "waste of time". "Right... Got anywhere to be right now or is your plan to finish your task till 11 and spend the rest of the day scrolling through facebook?" Common occurrence for that guy as a matter of fact. We've fought for years to take out the "we need that eod" to transition to long enough periods with realistic deadlines and plenty of time to spare for tests, documentation and so on. And it is something that we have now. It is proprietary software but the postgres example is perfectly valid - simply look at it.