HN Explorer

How to deal with developers who lack standards?

9 points by hotz ↗ HN
How do you deal with developers that don't comment their code? They're fully aware that they should and that it's the decent thing to do or when they update functions and move things around, they actually remove the comments.

Things like PEP8 or PSR-2 mean nothing to them.

I could also mention changing functionality, but not making sure that the tests are updated.

14 comments

[ 4.5 ms ] story [ 44.5 ms ] thread
onion2k
Tools not rules!

Use hooks to check quality automatically on your repos and/or CI server. Change the environment so a developer can't push code unless linting and tests pass. If you configure the remote to use receive.denyNonFastForwards they won't even be able to use --force. Then add linting rules so you have to comment things (eg https://eslint.org/docs/rules/valid-jsdoc). It won't enforce quality, but that comes later once people habitually know to write comments.

Expect a lot of resistance to this sort of solution though.

hotz
I've tried that. I was seen as having a stick up my a*. I've given up on enforcing it on that level.
jerry40
Why do they remove comments? Do they delete commented code or textual comments?
hotz
Your standard docblocks, even if the docblock explains what the function does if it's not clear. You'll basically have a function with zero comments. It's painful, I've never been given a reason as to why.
chatmasta
Why can’t you just read the function itself?

Maybe the real problem is people writing code that is so hard to understand you need a comment to explain what it does.

greenyoda
- Even if some code doesn't need a comment to explain what it does, you may need a comment to understand why it does it, or why it does it in this particular way (which seems non-obvious but is the result of the obvious approach having previously failed).

- Some algorithms are inherently complex and difficult to understand, so they may actually need comments to explain how they work.

- If code deals with entities in the real world, like bank accounts or car engines, it may be subject to rules that are not obvious just from reading the code. Comments can explain the relationship between the code and the domain the code is operating in.

ManlyBread
On my past job I was dealing with something like this and in my opinion source files aren't the best choice for a place to contain such information. To me having a quick reference to an internal documentation is the best: it's just a one line on the screen and when you need to update the information you have a centralized place to do so. If you have programmers that actually give a damn said programmers can learn ins and outs of the domain more easily this way, not to mention that this knowledge can serve non-programmers as well (for example help your support team in solving the issue without engaging the developers of giving your manager visibility into the internals of your work).
gary__
I'll hazard a guess that it's because it's quicker to delete than update them.
camhenlin
Is the code readable without comments? The team that I am on tends to (at least attempt!) write verbose code with long variable and function names, to obviate the need for comments. We do use comments for pointing out particularly difficult pieces of code or code that exists in a specific way for a specific reason, but we tend to think that most comments that people write are unnecessary
gary__
I took this approach after reading Clean Code, though I must say, I often regret not adding the comment as well when I return to the code much later. Still try to make the code as readable as possible though.
ajeet_dhaliwal
How do you know they are fully aware? May be they are not. I’ve been programming for almost 20 years and I’d never heard of PEP8 or PSR-2 until you mentioned them, granted I don’t do much python or php work.

May be the environment they are working on constricts them. May be they are pushed to deliver ASAP and given no time to think about maintainability because management doesn’t care about technical debt.

If you want higher standards drive it through by giving talks to your team and suggesting a style guideline be adopted to whoever the tech lead and introduce code reviews to ensure this adhered to.

seattle_spring
What are the comments? Usually people that complain that I don't comment enough are also the ones that add extremely useless comments like:

    // Return this
    return this;
timojaask
Have you discussed it with them? Did you ask them, without judging, why do they feel that it's better to delete the comment rather than update it? I'm wondering what kind of answers would come from them.

Who knows, maybe they have a legit reason for the behavior. Or maybe they simply did not give it enough thought. Either way, the humane appreach, talking, could help here.

tucaz
Fire them. If you are specifically asking for a task to be done (add comments) and they are not doing it anyway it is the same as not doing some other task.

If you don’t fire them even after talking and asking them to change their behavior then stop complaining and accept it as a fact of life.