Re: succinctness = power

[Paul Graham <address@hidden>]

Programs should have documentation, sure, and an API spec
would count as that.  Those of you who've written to
defend comments will notice that I said comments are
"often" an artifact of weak languages.  I'm not saying
programs should have no comments, just that you should
not have to have five lines of comments at the top of
every subroutine the way I was taught in college.  --pg

--Robert Bruce Findler wrote:
> At Mon, 3 Jun 2002 11:09:02 -0400, Timothy Hickey wrote:
> > 
> > On Monday, June 3, 2002, at 10:43 AM, Robert Bruce Findler wrote:
> > > As others have pointed out, the problem is that programmers do not
> > > maintain the comments as they maintain the program. I think that this
> > > is an entirely different problem.
> > 
> > This argument supports the use of "executable comments" such as
> > assertions or contracts that not only explain what the program is doing
> > but that signal errors at runtime or compile time when the program 
> > changes
> > and the "comments" do not.
> 
> Absolutely! In fact, my dissertation is about this kind of contracts.
> It shows how Eiffel mis-enforces such contracts and how to enforce them
> for languages with higher-order functions. These contracts make a huge
> difference, in my experience.
> 
> I'm not sure that this helps with things like API documentation (which
> must be kept in sync with the code) or "introduction" style comments,
> however. In DrScheme, there are lots and lots of little APIs (and
> several big APIs) around for various tasks. A language's primitives can
> even be viewed as such an API. No one wants to read the implementation
> of the run-time system to try to figure out what `car' or `+' does!
> 
> Robby