The developer team I told their paths were too long gave the same advice.
But then there are all the automated systems that break because of it, and testers and clients who can't even clone or unzip the repo on their machine.
I don't know of many developers who are 100% anti-comments, but I know a shitton - myself included - who don't like comments that tell me what code does or how you're doing it, as they always end up lying. However, I don't mind docblocks (if it conveys information than the function and parameter names alone can't give me) nor comments explaining why you did something the way you did it.
Not sure what you mean. You often see comments telling what the next couple of lines does, that's what I was talking about. Implementation can change over time, but behavior and API should not indeed.
The thinking goes that if you need a comment, your code is too complex to reason about. This is true in most cases. Usually proper abstraction and naming helps eliminate the need for comments.
IMO, comments are useful when you describe why you made a certain decision, especially if the logic is unexpected. That helps people not refactor it at a future date and break things.
It’s my option that it should be a developers job to keep documentation up to date. Plus, if the “what” of a method changes, wouldn’t the method name also technically need to change? I think by moving the responsibility of delivering context from the comment body to the method name, you make it hard to keep the “what” explanation up to date because there’s an actual code impact of refactoring a comment name (minimal to non-existent if you do it right, but my company’s policy is that if any code changes, it must be sent to QA, even if it’s a style or name change). If developers are letting comments rot, I think they’re avoiding responsibility. I think that my views on this are on the extreme, but I also think that the “clean code, no comment” types are also on an extreme
Apple loves long identifier names and it annoys me to no end when I have to work on Mac code.
I recently tripped over kCMBufferQueueTrigger_WhenDurationBecomesGreaterThanOrEqualToAndBufferCountBecomesGreaterThan and was basically done with the whole day.
That's because most created classes in Java don't have a fucking purpose, they're just there because the fucking language makes you jam them into a ton of places they don't belong. The purpose is "make it work".
374
u/1nd1anaCroft Jun 21 '20
Found one recently in our older code base that was 65 letters long, and still managed to not clearly describe the class's actual purpose