Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.programming > #1982

Re: self-documenting code? a pipe dream?

Show all headers | View raw

bob <bob@coolfone.comze.com> writes:

>Is anyone still trying to write self-documenting code that people just
>automatically know how to use?

>Or is this largely a failed concept?

I think people think that self-documenting code can do more than it can.
It is one thing to have clear, obvious code. That sort of code does what 
it should and communicates to the reader clearly what it is doing. In 
that sense, I think that modern languages and especially some research 
class languages have made strides in clearly communicating what they are 
doing.

This assumes that someone knows the language. I think it is silly to 
expect someone who does not understand the language that they are reading 
to be able to read the code. That is why making everything look like 
English is, to me, a bad idea. 

Notwithstanding the progress made in clear semantics, just understanding 
a piece of code does not allow you to understand the ecosystem in which 
it exists, its faults, intentional design limitations, or any of the other 
"why?" questions that we would like to know. Unfortunately, programmers 
have a hard enough time with just making code clear, and they seem to do 
a very bad job of clearly documenting the entirety of a system. Even if 
they do clearly document the isolated cases of which an ecosystem is 
composed, which can be helpful, and which often takes the form of 
some sort of API documentation (Doxygen, JavaDoc, man pages, &c.), 
that still is not enough to be really good, or even sufficient. So much 
more information, such as intended use cases, expected limitations, 
or even simple things like "where do I start?" or other global questions 
about how the web of code that one stares at fits together simply go 
unanswered.

Doing this well, IMO, requires a shift in perspective, from writing code 
to be compiled on the machine and to execute, to writing code with the 
intention that the primary purpose of the code is to communicate intentions 
and ideas to humans. This sort of perspective change is usually considered 
unimportant, or, more commonly, dangerous to the intended programming 
methodology. I think this is a mistake.

I think of sparsely commented code, or poorly commented code, which 
includes comments but does not actually provide order or structure for 
reading, as the scribbles of a mathematician. There are lots of ideas 
and symbols sitting around, but that's it. You never want to read those 
math scribbles, and I think it is a mistake to expect programmers to 
read what amounts to the scribbles of other programmers. Instead, we 
as programmer's ought to provide and expect to receive the programmer's 
equivalent of polished mathematical papers. 

I think there are different, viable ways to get there. But I think the 
most important thing is to have a way of presenting code that provides 
a path through which we can understand the code progressively from 
start to finish for the parts that interest us. It should read like 
a good book or a paper, not like notebook scribblings. I have seen 
this done with plain text, html, and other methods, but the most 
brilliant and pleasant presentations of code that I have seen come 
from those who put effort into writing literate programs. Things like 
the Stanford GraphBase are fun to read because you actually *read* them,
rather than deciphering them. You aren't put into the position of trying 
to divine why something exists; you get the reasons from the authors.

I happen to think that putting this sort of discipline into programming, 
using some literate form of programming, leads to better designed programs, 
and programs that have fewer bugs and that are easier to maintain. There 
are lots of tools out there for doing this, but programmer's seem averse 
to putting themselves into the role of being authors and writers for 
a human audience, rather than hackers talking to a computer. 

So, self-documenting code is not a failed concept, but you need to couple 
clear code with clear prose; one cannot live without the other, no more 
than a clear set of mathematical formulas cannot exist happily without 
clearly written prose together in a single artifact that expresses the 
whole intent and idea of the "product" or system.

-- 
-- 
Aaron W. Hsu | arcfide@sacrideo.us | http://www.sacrideo.us
Programming is just another word for the lost art of thinking.

Back to comp.programming | Previous | Next — Previous in thread | Next in thread | Find similar

Thread

self-documenting code?  a pipe dream? bob <bob@coolfone.comze.com> - 2012-07-18 11:18 -0700
  Re: self-documenting code?  a pipe dream? malcolm.mclean5@btinternet.com - 2012-07-18 12:05 -0700
    Re: self-documenting code?  a pipe dream? Daniel Pitts <newsgroup.nospam@virtualinfinity.net> - 2012-07-18 12:50 -0700
  Re: self-documenting code? a pipe dream? Aaron W. Hsu <arcfide@sacrideo.us> - 2012-07-18 19:24 -0500
    Re: self-documenting code? a pipe dream? Nick Keighley <nick_keighley_nospam@hotmail.com> - 2012-07-19 01:21 -0700
      Re: self-documenting code? a pipe dream? Aaron W. Hsu <arcfide@sacrideo.us> - 2012-07-19 16:07 -0500

csiph-web