

How can I deal with a team member who dislikes making comments in code? - iProject
http://programmers.stackexchange.com/questions/185923/how-can-i-deal-with-a-team-member-who-dislikes-making-comments-in-code

======
malandrew
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
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

      "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.

------
LoneWolf
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
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-U...](http://www.codeodor.com/index.cfm/2008/6/18/Common-Excuses-Used-
To-Comment-Code-and-What-To-Do-About-Them/2293)

------
lutusp
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.

~~~
malandrew

      "... is the behavior of someone who isn't accustomed to 
      working with other people."
    

exactly.

------
chatmasta
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.

