2

I have function that takes as arguments a number of classes of average complexity.

When writing docstring for that function, I'm running into a series of questions: Should I describe (besides what the function is doing) those classes too, or can I assume that the reader will dig up the class definition? Or should I point to where the classes are defined? What is the best practice?

  • Does your function take classes (which are first class objects in Python) as arguments, or does it take instances of classes as arguments? – David Hammen Apr 13 '18 at 14:20
5

Any modern IDE should allow the reader to jump to the definition of referenced classes at a single mouse click. There is no point in repeating this information (denormalization of data is sometimes a good idea, but not in software documentation).

Therefore, when a StringDistance method takes Strings as arguments, you should certainly not describe what a String is; when a LoanRiskCalculator uses Loans, you probably shouldn't describe Loans either. That information is better placed within the Loan class.

The edge case is when the argument classes are dedicated helper classes that are more or less useful only for use with this method or this class. Then it can be a good idea to describe them together with the algorithm that they serve. A StringDistance method that uses ReverseTrieLookupTables to communicate with associated other methods might pull the documentation of thease specilized helpers into its own docstring, or at least into the class docstring.

3

The specific term docstring you are using indicates that you are using Python. (Or Cobra, but the latter one is far less likely.)

Note that in Python, what is relevant is the protocol, and not the class of your parameters. (This is called duck typing, or really just OO.) So, you shouldn't document the class at all neither by reference nor by copy. The definition of those classes is completely irrelevant.

What is relevant, is what protocol your function expects from its parameters. You should document that. Also, you should document what protocol your function guarantees for its return value.

  • +1, but I don't understand what exactly you mean by "protocol" (the wikipedia article en.wikipedia.org/wiki/Duck_typing does not contain any mention of this). Could you please elaborate? – user7088941 Apr 13 '18 at 13:30
  • The term protocol is much older than the term duck typing. It is a general OO term. It means the set of messages an objects understands and how it responds to them. – Jörg W Mittag Apr 13 '18 at 14:02
  • @user7088941 I think Jörg is trying to say that when you design a function you don't always know exactly what will be passed to you as a parameter (what class, what implementation) only how you'll use it (protocol, duck typing). Therefore your documentation should reflect that reality, not make a bunch of assumptions. – candied_orange Apr 13 '18 at 19:36
  • 2
    For example, if you write a sum function, you don't care that your parameter is a list of ints. What you do care about is that your parameter conforms to the iterable protocol and that its elements have an __add__ method that returns something that also has an __add__ method. That's it. That way, you can sum lists of integers but also sets of strings or stacks of lists. – Jörg W Mittag Apr 13 '18 at 19:41
  • @JörgWMittag I understand now what you mean, thank you! But are you really sure that it is a good idea to write docstrings solely by having the protocol in mind? Because the docstrings will end up become pretty useless in that case, since they will be much too cryptic/abstract: Imagine I'm doing a few string operations inside a function, taking two arguments that are arrays of strings as input. I want to write a docstring for this function. [...] – user7088941 Apr 14 '18 at 10:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.