Hacker News Reader

Comment by joekrill | Hacker News Reader

I hear this all the time as to why comments are "bad" (and I'm not suggesting that's what _you_ are saying, btw). Comments need to be kept up-to-date with code changes. The same way unit tests are kept up-to-date, and everything else around your code is. Comments are no exception.

View on HN

The thing is, if somebody forgets to update a unit test, it immediately becomes obvious. If somebody forgets to update a comment, it's very easy for no-one to notice until it's much too late. There's no way to automate that check.

In terms of developer resources, the act of doing updating the comments is cheap, but the act of making sure it gets done (in a systematic way) is comparatively expensive.

To miss comments in the code, developer must be blind. Maybe you are telling us about sad story of external documentation?

This isn't true, especially when you're dealing with legacy code that is overcommented. Your brain will learn to tune them out.

But it's not immediately obvious if someone changes something that isn't covered by a unit test. Or forgets to create a unit test. Does that mean we should just abandon writing unit tests altogether?

You could always use a tool like Danger (http://danger.systems/) to inspect your code and warn you when code has been updated, but comments nearby have not been.

> But it's not immediately obvious if someone changes something that isn't covered by a unit test. Or forgets to create a unit test.

This is what code coverage analysis/metrics try to address.

> You could always use a tool like Danger (http://danger.systems/) to inspect your code and warn you when code has been updated, but comments nearby have not been.

I'd worry about tuning out said warnings after too many false positives. Comments regular enough to not generate too many false positives can generally be turned into real syntax of some description.

So add comments to your code review process. This really isn't hard.

For example: python functions shall have a docstring unless trivial. For external api functions on a class, there must be at least one example. etc etc. Plus, this makes working in ipython really nice!

I usually apply something like this except only for public methods; I figure if you're digging around the private methods you probably need to look closely anyways.

Unit tests fail when they are out of sync. Guess what? An out of sync comment will never fail.

>Comments are no exception.

but they usually are.

Well this seems like a problem with code reviews (or lack of), rather than with the comments themselves.

It's a matter of incentives. Business folks don't care about comments unless they have a dev background. Your options are then to focus on the incentives present in the situation, or materially harm your own life and well-being by working extra hours to make up for your management's inability to manage.

I hate this excuse. It seems like every lazy habit of programmers gets pushed onto the "business folks".

Just because business folks don't know how to value certain developer practices doesn't let you off the hook. Just do what you have to do and if it takes longer because you had to learn how to do it, then it takes longer.

Let the business folks tell you when it's taking too long to deliver features.

But it does. It depends on the organization, but there are groups where chugging coffee, talking a lot, and pumping out dozens of half-working features by coding like a drunk cowboy will get you promoted and recognized as a team player, while pushing back to take time and do things right will have you reprimanded. Many such cases out there.

My point is that you shouldn't push back. Just do things the way they need to be done, and it takes as long as it takes.

A manager looks at a programmer bringing up something like unit testing as "why the fuck is he asking me about this, it's his job? Obviously because he's asking me it's outside of his professional ken, so that means it's going to take absolutely forever." Out loud he'll just say, "Can you just get the feature done?"

Don't ask, just do it. It takes as long as it takes. If they ask, just say it's not done yet.

This generally won't work for straight forward game theoretic reasons. Boss thinks you're slow->boss brings on h1b consultant willing to pump out spaghetti code and toady up to him->you looking for a new job. Organizations get what they ask for

The boss doesn't have to think you're slow. You could... gasp... be good at your job.

I can tell you're upset, Vince, so I'll be the one to end this discussion.

Being good at your job won't magically make you fast at fixing up other people's spaghetti code. It won't let you ship 3 working features faster than someone else who's also "good" at their job ship 6 mostly broken features. It won't convince your manager that the former is actually getting more work done than the latter, and won't prevent them from thinking the first guy is slow and the second guy is fast.

But for what it's worth, I agree with you in that I'm still on the hook. Either to help educate my manager, or to pick managers who already understand this stuff.

In my company, the business folks have no idea what the code looks like or whether or not there are comments.

All they care about is that the code works, and that features can be delivered on time.

That second part "delivered on time" includes maintaining the comments along with the code since it makes the code more readable, and eases future changes. If Management doesn't give you time to write maintainable code (which includes keeping comments in sync with the code), then you may as well start looking for a new job because the technical debt is going to pile up and it's going to get harder and harder to meet deadlines.

They don't care about comments, per se, but they probably care about whether someone else can easily work on the code. I'd think (hope) most technical managers are going to encourage some sort of team review of the code and not get all the way into the weeds about what specific issues in the code review need attention.

Would be cool to have a utility that embeds a hash of the function in the comments, and could check automatically. So if a function changes and hash doesn't the user would be alerted.

I find that I have this problem with my own code. Ridiculous, but it happens.

Reply on news.ycombinator.com