[racket] Why experienced programmers don’t use comments?

On Jul 8, 2013, at 9:41 PM, Ben Duan <yfefyf at gmail.com> wrote:

> Dear All,
> 
> I have a question here. There’s an extensive use of comments in HtDP. But there are few comments in experienced programmers’ code, for example in racket’s source code. Why is that?

Ben, 

let me assume that your question denotes "why does HtDP preach a certain style of commenting when its authors and their colleagues don't seem to follow their own advice in their own code base." If you meant to have a general idea of why old C programmers write "x is incremented by 1" next to "x = x + 2" and fail to state the invariant for the loop below this assignment statement, see blogs/guru sermons/or whatever is currently popular culture on programming on the web. 

A couple of answers: 

1. As Sam points out, his part of the code base has a comment/total lines ratio of 10%. I just went to two directories of my share of the code base and it is closer to 15%. That is a bit more than HtDP would ask for if you interpret HtDP's advice naively. 

2. I would like to think that HtDP should be interpreted widely: files, classes, units, etc all need purpose statements and some sketch of a 'type' signature. 

3. But, if you look into other parts of the code base, you will find far fewer comments, occasionally below the 1% threshold. What gives? 

-- Part of the problem is that comments aren't checked so there are all kinds of problems associated with them. Most importantly, they are out of sync. 
-- Experienced programmers react to that by writing fewer and fewer comments. 
-- If they were reflective and wanted to drive this line of argument to the end, they'd program in languages
   such as Agda or Coq where you can say almost everything about your program you ever imagined saying. 
-- But then we'd still wait for the first piece of software to do anything, something good for the world.
-- So experienced programmers balance the ideas of 'get things done now' and 'someone will read this code one day and will not be able to understand it (including myself)'. 
-- The compromise ends up closer to the first perspective then the second. 

4. In short, comments are the weakest element in the process and thus neglected. That does not mean that neglecting them is good. 

;; --- 

Do contrast this insight with 'testing' and the comprehensive test suite that Racket comes with. Testing is checked almost every time we change anything and so it is a strong link. 

;; --- 

As for the design recipe over all: the idea of HtD is that programmers internalize this mode of thinking and follow it w/o making every step explicit. When I read someone else's code though, I often recognize the ideas of HtD and how they were applied in a specific context. This helps me comprehend the code much faster and places me often in a position where I can quickly discuss (and possibly execute) changes. 

-- Matthias