1

Tests can be very nicely written down using the given-when-then style. Are there similar styles / templates for describing methods and classes in docstrings?


To clarify: There are many sites which describe the docstring format and give examples. According to them, functions and classes usually start with a one line summary. After that, a longer description follows. Is there any structure / template for this longer description?

I often find myself rewriting it several times trying to explain why certain things are implemented the way they are, what it shall be used for, what not, etc. Some common patterns I used but am not 100% content with are:

  • Problem: ... / Solution: ...
  • This is... / It was implemented like this because...
  • A was chosen over the usual B here, because...
  • Usually, method A would be used. However, it ... . Therefore, we...

Certainly this must be something some people have already faced and found decent solutions?

1
  • 3
    Docstring conventions tend to depend on the programming language ecosystem and the documentation generator used (e.g. Python/Sphinx, C++/Doxygen, Java/Javadoc, Rust/Rustdoc …). In any case, docstrings typically explain how the function or class can be used, not why it is implemented the way it is.
    – amon
    Oct 8, 2021 at 13:22

1 Answer 1

5

I often find myself rewriting it several times trying to explain why certain things are implemented the way they are, what it shall be used for, what not, etc.

This kind of information does not belong in docstring comments. IDEs read docstring comments to provide auto-complete suggestions, and you can create API documentation in HTML or PDF format. This information should describe what these methods, classes and parameters mean. Describing why code was written the way it was written is still valuable information, though.

Consider this code:

for (int i = 1; i < items.Count; i++)

It is subtle, but the loop starts at 1 instead of zero. There is a reason why this code was written this way (assuming this isn't a bug), so the comment describing why it was written this way should go above the code it describes:

// Start loop at index 1 instead of 0 because ...
for (int i = 1; i < items.Count; i++)

Some common patterns I used but am not 100% content with are:

  • Problem: ... / Solution: ...
  • This is... / It was implemented like this because...
  • A was chosen over the usual B here, because...
  • Usually, method A would be used. However, it ... . Therefore, we...

Items 1 through 3 a good use cases for simply adding comments to the code, rather than docstrings. The location of the comments should be right above or near the code it comments about. Item #4 could be in docstring comments, though.

Item number 4 — "Usually, method A would be used. However, it ... . Therefore, we..." — describes a situation where the order of method calls matters, or it describes a larger use case that provides context for why this particular method gets called. Many docstring formats allow you to specify some example uses for a method or class. How or when to use a method might fall into this category for docstring comments. Consider the following docstring comments (for C# if that matters)

/// <summary>
/// Calculates the baz from the foo
/// </summary>
/// <param name="foo">...</param>
/// <returns>...</returns>
/// <example>
/// Foo foo = repository.FindFoo(x);
/// Bar bar = new Bar();
/// 
/// int baz = bar.CalculateBaz(foo, 3)
/// </example>

The docstring format in Visual Studio allows you to specify any number of <example> blocks to illustrate different use cases or how to use a method. This could be useful when generating API documentation, so it belongs in docstring comments.

If the comment explains a design decision, then it should be put by the code whose design is being explained. If the comment would be useful in the suggestions provided by an IDE, or it would help explain how to call the method to other programmers, then docstring comments can be a good fit, provided the docstring format gives you a specific way to describing examples.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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