On 08/22/2014 10:14 PM, Volker Braun wrote: > On Friday, August 22, 2014 9:11:08 PM UTC+1, Ralf Hemmecke wrote: >> >> Well, of course, a name is just a name. So call the function 'foo' >> instead of 'nonzero'. Would you still be happy with the specification? >> > > I wouldn't be happy with the method name to start with. No amount of > documentation can save a badly-chosen UI. The aim should always be to be so > clear that the use doesn't have to look it up in the docs.
Maybe I should say that I'm on your side when it comes to name methods by full name and in such a way that they basically describe what they do. Nevertheless, the function name is not the specification. The point I want to make is that some programmer might have chosen a name that does not exactly describe what the function does, i.e. in some cases the reader of the API would believe something from the name that is actually wrong. Now suppose that in such a case the docstring is vague and somehow relies on the programmers (false) belief that he chose the name right. I guess you probably agree with me that this calls for bugs later. There should be no need to look at the source code in order to know the input/output behaviour of a function. The documentation should suffice. If the function is named well, that's certainly a plus, but the specification is what is really important, not the name of the function. For example, take "mod" and suppose the documentation says. For two integers a and b (b nonzero), a mod b computes the remainder of the division of a by b. Unless the programmer has specified somewhere what he means by "remainder", I wouldn't exactly know what this function does. Or would you know what mod(6,7) would return with the above specification? Does the name "mod" help you? Maybe you say, that name is bad. OK. Ralf -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
