Distinguishing between commented code and documentation

[shaperilio]

In Python, I use docstrings and comments for different things. Docstrings have to follow some format and be in a specific place (e.g. right under a function definition) and block comments can be one of two things: a) explanation of what code is doing. and b) temporarily commented-out code.

I'm transitioning from flake8 to ruff and it seems both of these tools treat docstrings and block comments (really a comment on a line by itself) as "documentation", and thus they both must adhere to the max doc line length.

I personally find this impractical; I often allow a code line length of, say, 100, while docstrings are set to 80. This makes it easier to read documentation (docstrings and block comments alike). My code lines tend to rarely end in the 80-100 range, especially after ruff format. Further, in my editor, I have a helper that wraps block comments and docstrings for me. So different line lengths work for me; with three or four editors wide on my screen, I can still read documentation without scrolling and can do so on the occasional long code line if necessary.

It's when I'm commenting out code during development that the problem arises. Suddenly, disabled code is "documentation" and now it, too, must be limited to 80 characters. With a linter as a pre-commit hook, this is not fun. With a linter as "display-only" (e.g. highlighting errors in my editor window) it's tolerable but not ideal. Perhaps I'd want to be reminded (via warning) that I have a block of commented out code there, but that should not show up as a line-length issue. And the line-length issue is relevant if, for example, I edited a typo in a docstring and my wrapping helper didn't reformat for me.

In short:

• I have different line lengths for documentation and code.
• Commented out code unfortunately becomes documentation and thus often violates my linting rules.

If ruff is going into docstrings to format code, it seems like it could inspect my comments and look for code, too - and then stop telling me it's too long before it hits my code length limit. I thought I'd ask here in case a) I missed something in the docs on how to do this or b) I'm the only one in the world who has this problem.