Re: Scwm docstrings change

["Greg J. Badros" <gjb at cs dot washington dot edu>]

mstachow@alum.mit.edu writes:

<snip>

> > Except that I'd like the post-processor to only have to deal with lines
> > that start with, say, %%%% as guile-snarf and scwm-snarf now do.  I can
> > actually get pretty darn close to the raw docstring output as it is w/o
> > any substantial postprocessing, but my goal is to just make the
> > postprocessing simple as it is fairly loosely coupled.
> 
> It sounds like that may place a lot of contstraints on where line
> breaks may or must go in the macro calls.

It's easy to work around that issue, too, and still avoid looking at the 
whole source file.

> > It's a solved problem one way, it's not solved the other way, and we
> > agree it's largely a matter of aesthetics;  I'm planning on moving
> > forward with the macro that keeps the coupling tighter and is more
> > concise.
> 
> I hope we can reach some sort of consensus before you integrate this
> with Guile.

I'm guessing we're not going to on the detail because I thought the
consensus was that it's an aesthetic issue.

> > > However, (warning, quarter-baked thought approaching) perhaps it would
> > > be better to make the macro include a scheme-style argument list, since
> > > this would allower better control of how the formal parameter names will
> > > look to the user. The function name is already written once in Scheme style
> > > and once in C style. Indeed there are already cases in the Guile sources
> > > where the Scheme and C names for functions or syntax do correspond in
> > > the canonical way (`atapply' would normally become the Scheme `atapply'
> > > rather than `@apply' for instance), and it may be the same thing might
> > > be useful for formal parameters in some cases.
> > 
> > We already do this in scwmdoc.  foo_p turns into foo?, etc.
> 
> I know this translation happens. My point was regarding names that cannot
> translate that way. `_p' to `?' at the end is a reasonable transformation.
> Prefix `at' to prefix `@' is not, IMO, because a word could very well 
> legitimately start with at - and there is no unambiguous way to
> represent that Scheme identifier in the C style.

I see;  I'm willing to burn that bridge if and when we come to it.

> > I just don't buy the argument about code readability.  Function
> > definitions *very* commonly exploit macros (see my research paper on an
> > empirical study of C preprocessor use) and better-than-novice programs
> > will only look twice before figuring out what's going on.
> 
> Pointer to paper please? I'm willing to recosider if this is widely used
> existing practice. But I still think it looks better with the function
> header separate.

It's off of my home page.  See:

http://www.cs.washington.edu/homes/gjb/#papers

I'm just not convinced by the "looks better" argument when I have real
software engineering arguments for making the coupling tighter.  (BTW,
my paper argues that it'd be great if we didn't have macro's obfuscating
the code; but it also demonstrates that it's common practice and
function headers are one of the most common places for that.  I'm
claiming now that sticking to conventions alleviates the difficulty, and 
in the presence of other benefits, those other benefits far outweigh the 
slight decrease in initial readability.)

Greg