octave-maintainers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Undocumented internal function


From: Jordi Gutiérrez Hermoso
Subject: Re: Undocumented internal function
Date: Wed, 1 Sep 2010 12:48:53 -0500

2010/9/1 Soren Hauberg <address@hidden>:
> By documenting these functions we are encouraging people to use it.

This, this is *precisely* the attitude that I want to deprecate. That
it's desirable and good to consciously choose to not document
functions and that we'd be doing some sort of damage if we document
them, that users need to be consciously herded for their own good.
It's a paternalistic attitude, that users are too dumb and we need to
steer them by not documenting functions.

I say, if a user has been curious enough to find the internal
functions, which they may well have found by reading source code where
they're called, we should *reward* that behaviour by telling them what
the function is (and prominently mark it as internal, in case they
wandered there by mistake).

This attitude is disrespectful to users. Treat all of your users as
potential developers and peers, not as a flock of sheep that needs to
be herded.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]