[REQUEST] Allow rules to be enforced for private items

[markustoivonen]

Hi!

Has there been any discussion about allowing pydocstyle rules to be enforced for private modules/classes/functions/etc., just as they are for public counterparts by default? I would really love to see this feature available.

Thanks!

[sigmavirus24]

Why do you want this for private items? You want to force everything to have a docstring? Why? What value do you see in that?

[markustoivonen]

You want to force everything to have a docstring?

Yes, exactly!

Why? What value do you see in that?

The issue came up in my team, where we use private functions, but cannot enforce the docstring rules to them. This leads to scenarios were might add complex-enough code (subjective definition) into production with no docstrings for example.

[sigmavirus24]

That sounds like a team problem that code review should catch because enforcing docstrings for everything will be far more toil and will likely be turned off after not too long.

Alternatively it sounds like you want to use something like McCabe or Radon to reduce complexity of these so that they don't need docstrings or a significant amount of toil

[markustoivonen]

That sounds like a team problem that code review should catch

Yes, I agree CR should catch this, but human errors happen, which is why I would want to enforce it.

because enforcing docstrings for everything will be far more toil and will likely be turned off after not too long.

With this I don't agree (at least until I would've had the chance to try it). We already write docstrings for all public versions for code that goes to production (we don't disable any rules), so the requirement would just be added to the private functions?

Let me pose it from this angle: what harm is there to implement this with an opt-in flag (if we ignore the work required from maintainers)?

[sigmavirus24]

Let me pose it from this angle: what harm is there to implement this with an opt-in flag (if we ignore the work required from maintainers)?

Which work are you ignoring? The work to create the behavior? The work to maintain an almost certainly to be rarely used feature with branches in many parts of the codebase? The work to explain to people that they're seeing unexpected behavior because someone turned the flag on so what they may expect will be different from how it was configured (given the long and storied history of trying to improve the 'What even is private? ' heuristics)? The work of figuring out of anyone even uses this and it can/cannot be deprecated in the future?

None of that is trivial averaged over time. And no, volunteering to help maintain this one feature doesn't help.

---

As for toil, any sufficiently large project (closed, or open) may be using pydocstyle in some fashion to have docstrings for the benefit of maintainability. That's great. At some point, something goes wrong, like it did for your team, and one proposed solution is let's docstring everything. That may seem reasonable at first. But in my experience, private methods are private to reduce the burden of maintaining them or to hide some complexity that should already have at least one comment. More often than not, they're for reducing repeating one's self for trivial code blocks. The more of these you have the more toilsome creating docstrings will be. The more likely a team is to turn this back off because it was never really the right solution.

You argue that you don't agree, not until you have tried it at least. But that's completely unreasonable. We won't work on a feature and release it generally just so you can take it for a spin. Fork the project, maintain your fork and use it for a year and let us know how that goes. My bet is that within a year or two, your team will be turning off that flag.

[markustoivonen]

Thank you for taking the time to give such a thorough answer.

You raise good points that I hadn't thought of, but also some things that I see differently. However, it seems that further discussion about this issue has no effect on the outcome, which is that this feature will not be considered for implementation. Thus, I will be closing the issue.

All the best and thanks for all the work in the realm of Python code quality!