5 ms·

How can I deal with a team member who dislikes making comments in code?

7 points by iProject 14y ago

lutusp 14y ago
In such a case, I would create a new employment requirement that one's code must be commented well enough that another programmer can take over, productively, in a short time. Not commenting code, not naming variables and functions in a way meant to reveal as much as possible, is the behavior of someone who isn't accustomed to working with other people. So it should be made a requirement for employment, end, full stop.
- lighthazard 14y ago
  That does quite a number of morale.
- malandrew 14y ago
  "... is the behavior of someone who isn't accustomed to working with other people." exactly.
chatmasta 14y ago
Or, instead of inventing some elaborate incentive system, you could simply convince him to put comments in his code (clearly the better practice). If you can't convince him of that, you need to work on your sales capabilities.
LoneWolf 14y ago
Someone once said to me (I can't really remember who) "Good code does not need comments, it should be easy enough to understand without them, if not then it is bad code." I think that if the code is not easy to understand without heavy commenting then the problem may even be the quality and not the lack of comments. Most code I write does not have much comments, they are mostly API documentation or the reason why I did something in a specific way, other than that I feel like they are useless, they don't add value, the variable and method names are and should be enough to know that they do or represent.
ville 14y ago
I don't think there's a need to "deal with" them. Writing self-describing code is better than writing code that requires comments to be understood. Writing obvious comments that tell what could be read from the code is bad because now you need to maintain the comment as well or it becomes outdated making it much worse than no comments at all. You should focus on the code not being self-documenting enough, not the lack of comments. Here are some excuses people use to justify comments: http://www.codeodor.com/index.cfm/2008/6/18/Common-Excuses-Used-To-Comment-Code-and-What-To-Do-About-Them/2293 http://www.codeodor.com/index.cfm/2008/6/18/Common-Excuses-U...
malandrew 14y ago
In languages with no typing, the lack of comments can be a huge pain and the code often is not self documenting. In many cases where types are simply strings, arrays, ints, floats, etc. the code can most certainly be self documenting, but this isn't really true for custom complex datatypes. I was working on a project where another developer (a classic BBM) had created his own recursive tree data type that wasn't defined anywhere and was referred to using a different name in the myriad functions that operated on it. In a situation like that comments or documentation of some sort helps immensely. This code wasn't clear for a long time until I sat down that developer and worked through that data type and all the different forms the branches and leaves could take. The code still needs refactoring to make naming consistent. "Show me your code and conceal your data structures, and I shall continue to be mystified. Show me your data structures, and I won't usually need your code; it'll be obvious." --esr (paraphrasing fred brooks in TMMM)
- bunderbunder 14y ago
  Excellent point. I've also found that situation (though admittedly to a lesser extent) in languages that are dynamically typed. My first experience with Python rapidly turned sour when I discovered that I was going to have to use guess and check to figure out what types of parameters some functions in a standard file-handling library expected. The less discipline the compiler demands of the programmer, the more discipline the programmer should demand of himself.
  - malandrew 14y ago
    "The less discipline the compiler demands of the programmer, the more discipline the programmer should demand of himself." That's a great way of putting it. Completely agree.

7 points by iProject 14y ago

In such a case, I would create a new employment requirement that one's code must be commented well enough that another programmer can take over, productively, in a short time. Not commenting code, not naming variables and functions in a way meant to reveal as much as possible, is the behavior of someone who isn't accustomed to working with other people. So it should be made a requirement for employment, end, full stop.

lighthazard 14y ago
That does quite a number of morale.
malandrew 14y ago
"... is the behavior of someone who isn't accustomed to working with other people." exactly.

chatmasta 14y ago

Or, instead of inventing some elaborate incentive system, you could simply convince him to put comments in his code (clearly the better practice). If you can't convince him of that, you need to work on your sales capabilities.

LoneWolf 14y ago

Someone once said to me (I can't really remember who) "Good code does not need comments, it should be easy enough to understand without them, if not then it is bad code." I think that if the code is not easy to understand without heavy commenting then the problem may even be the quality and not the lack of comments. Most code I write does not have much comments, they are mostly API documentation or the reason why I did something in a specific way, other than that I feel like they are useless, they don't add value, the variable and method names are and should be enough to know that they do or represent.

ville 14y ago

I don't think there's a need to "deal with" them. Writing self-describing code is better than writing code that requires comments to be understood. Writing obvious comments that tell what could be read from the code is bad because now you need to maintain the comment as well or it becomes outdated making it much worse than no comments at all. You should focus on the code not being self-documenting enough, not the lack of comments. Here are some excuses people use to justify comments: http://www.codeodor.com/index.cfm/2008/6/18/Common-Excuses-Used-To-Comment-Code-and-What-To-Do-About-Them/2293 http://www.codeodor.com/index.cfm/2008/6/18/Common-Excuses-U...

malandrew 14y ago

In languages with no typing, the lack of comments can be a huge pain and the code often is not self documenting. In many cases where types are simply strings, arrays, ints, floats, etc. the code can most certainly be self documenting, but this isn't really true for custom complex datatypes. I was working on a project where another developer (a classic BBM) had created his own recursive tree data type that wasn't defined anywhere and was referred to using a different name in the myriad functions that operated on it. In a situation like that comments or documentation of some sort helps immensely. This code wasn't clear for a long time until I sat down that developer and worked through that data type and all the different forms the branches and leaves could take. The code still needs refactoring to make naming consistent. "Show me your code and conceal your data structures, and I shall continue to be mystified. Show me your data structures, and I won't usually need your code; it'll be obvious." --esr (paraphrasing fred brooks in TMMM)

bunderbunder 14y ago
Excellent point. I've also found that situation (though admittedly to a lesser extent) in languages that are dynamically typed. My first experience with Python rapidly turned sour when I discovered that I was going to have to use guess and check to figure out what types of parameters some functions in a standard file-handling library expected. The less discipline the compiler demands of the programmer, the more discipline the programmer should demand of himself.
- malandrew 14y ago
  "The less discipline the compiler demands of the programmer, the more discipline the programmer should demand of himself." That's a great way of putting it. Completely agree.