Re: Wondering if you guys would like to comment on this

David Steuber wrote: 
Ulrich Hobelmann <u.hobelmann@xxxxxx> writes:


What I meant is that I prefer reading usage documentation to reading
code by other people, because all that code distracts from the usage
info that's all I want.

Therefore I expect a macro (especially since it is more powerful than
a function) to be well-documented.



What do you do when your expectations are not met?


The same I'd do if Sun had crappy documentation, or anyone else: tell the programmer. If he isn't around anymore (and if I have the code and have to maintain it), take time to decipher the macro code and document it. Maybe the original coder can be reached by email and answer questions, too.

Still, documentation is important. Reading code can only tell you, *how* stuff is done, not always why.

--
No man is good enough to govern another man without that other's consent. -- Abraham Lincoln
.

Relevant Pages

  • Re: Macro concern and advice wanted
    ... David Steuber wrote: ... To my neophyte eyes, it looks like I have an implicit eval ... As far as I can tell, your macro doesn't handle this case at all. ... checks for a keyword in various places, and if none of the tests succeed ...
    (comp.lang.lisp)
  • Re: Macro concern and advice wanted
    ... David Steuber wrote: ... >> As far as I can tell, your macro doesn't handle this case at all. ... compile time, not run time, so it won't see the run-time variable or ... they won't be accessible at all -- EVAL uses the global environment, ...
    (comp.lang.lisp)
  • Re: Macro concern and advice wanted
    ... David Steuber writes: ... >> Write a function that can be used with evaluated data, ... >> macro when literal data is being provided. ...
    (comp.lang.lisp)
  • Re: Whats so special about IF?
    ... David Steuber writes: ... This macro doesn't deal properly with multiple values owing to the way ...
    (comp.lang.lisp)