vscode
vscode copied to clipboard
microsoft
Revert Python docstring color
This is a temporary fix of #184836 and reverts PR #182162.
Motivation:
- Both the old behavior and the current are WRONG. Neither of them should be preferred in favor of correctness.
- This behavior change is too disruptive to user experience and many people got confused by this sudden change.
Therefore, I'm proposing to revert the change and go back to the old behaviour in the next release. The issue will not be closed by this and we should eventually find a correct solution.
Reminder, here is how to fix the colors for yourself:
If you do this change and then click the little person icon in the bottom-left of VSCode, and sign in with GitHub (or one of the other sign-in options) and turn on sync, it will apply this change to all instances of VSCode you have, on all computers you have.
@aeschli is there anything that members of the community can do to help progress this PR? It looks like quite a few people have validated that this achieves the expected result (i.e: reverting back to the previous behaviour).
I think it's fair to say that where we go from there is more complicated, though reverting to the previous behaviour feels the best option given how contentious this is. That would then give the VSCode team (along with the VSCode-Python team and the community) time to discuss the options and work out a migration strategy for affected users of whatever change happens (if any change happens).
I find it quite shocking that an incorrect and unwanted change was merged in just 4 days and with only 2 reviewers, but an almost universally agreed upon correction is taking more than a month to merge and needs apparently 11 reviewers?!?! The community doesn't seem to have any power to correct this mistake.
I find it quite shocking that an incorrect and unwanted change was merged in just 4 days and with only 2 reviewers, but an almost universally agreed upon correction is taking more than a month to merge and needs apparently 11 reviewers?!?! The community doesn't seem to have any power to correct this mistake.
I am inclined to say this is a failure of the project maintainers.
Since @aeschli isn't responding, @dbaeumer is there anything you can do to help out?
I find it quite shocking that an incorrect and unwanted change was merged in just 4 days and with only 2 reviewers, but an almost universally agreed upon correction is taking more than a month to merge and needs apparently 11 reviewers?!?! The community doesn't seem to have any power to correct this mistake.
I am inclined to say this is a failure of the project maintainers.
I honestly would love to hear why "It makes sense to render docstrings as comments", considering this is completely against the style guide and its entirely objective that doc-strings are NOT comments.
Don't they think that if this made sense, that someone might have proposed it before? We've literally been rendering doc-strings in a different colour to comments for many years, and no one has been asking to change it. Did they not consider that that might be an indication that its that way for a reason?
It has since been fully explained in the original PR as to why the change was incorrect, and yet its been completely ignored by both the original reviewers.
It'd be nice to see an apology for the mistake, and then some kind of review as to how this happened and why it is taking so long to correct.
It'd be nice to see an apology for the mistake
Let's keep things community spirited 😊 I think it was a mistake, and it is indeed frustrating that this is taking so long, compared to the first change, but that is as it is.
Asking for apologies, borne from frustration, feels counter productive.
then some kind of review as to how this happened and why it is taking so long to correct.
I would suggest better guidelines around approving changes to existing behaviour, that aren't operational bugs.
Linux kernel's mantra of "don't break userspace" comes to mind.
In this case, the change did two things
- added a way to customize python docstrings specifically (not actually a bad move)
- used this, and customized docstring theming to a single user's preference, forcing everyone else to work around it to return to original behaviour (a bad move)
What we might be able to extrapolate from that as a guideline for future approval processes, I cannot say for sure.
My suggestion though would be to ask
- Is it possible to request/ensure the change allows the prior behaviour to continue as default?
If so (therefore an option is being introduced, rather than a bug being fixed), choose to pursue that route.
If not (this may affect bug fix changes), ask
- how many people will the change necessarily affect?
If it affects all users within a language/technology community, seek multiple maintainer involvement.
My 2c, for what they're worth 🪙. I hear inflation is high these days.
In this case, the change did two things
- added a way to customize python docstrings specifically (not actually a bad move)
- used this, and customized docstring theming to a single user's preference, forcing everyone else to work around it to return to original behaviour (a bad move)
I don't think the first of these is correct? I don't have an older VSCode to hand to test with, however looking at the original PR I don't see anything there which changes how the parsing logic worked -- only changes to how the built-in themes coloured tokens of various types. (Plus some tests changes)
The original PR even admits that this was already possible for individual users -- it includes a link to a StackOverflow answer written by the author on the same day they opened the PR which explains how to do it!
Your other suggestions for how to introduces this sort of change in a non-breaking fashion are completely valid though and are exactly what the VSCode team have done in the past.
In this case, the change did two things
- added a way to customize python docstrings specifically (not actually a bad move)
- used this, and customized docstring theming to a single user's preference, forcing everyone else to work around it to return to original behaviour (a bad move)
I don't think the first of these is correct?
@PeterJCLaw You're right. @taikedz The previous PR only changed the configuration of the bundled themes, based on existing infrastructure.
It'd be nice to see an apology for the mistake
Let's keep things community spirited 😊 I think it was a mistake, and it is indeed frustrating that this is taking so long, compared to the first change, but that is as it is.
I would generally agree, but they didn't ask the community about the change in the first place, and then are ignoring the community when asked to fix it? It seems to me, that the very least they could do, would be to apologise. Perhaps that just me.
What I do not understand, is why this issue has 11 approvals and can't be merged, but the original PR was merged with only 2 approvals? This makes no sense to me...
@hediet as you have some of the context from where this issue was raised on https://github.com/microsoft/pylance-release/issues/4429, are you able to provide any insight into how the community can help get this moving?
i do not support changing back.
At first i was "surprised" and though that i had some error with my linter or vs code configuration.
But then after looking into it and understanding the problem and more importantly, the rationalle for the solution, it makes perfect sense for doc strings / block quotes to be the same colour as other comments...
In fact, i always found it rather odd that block comments were a different colour to other comments.
So the correction imposed is actually correcting something that had historically always been incorrecy & i applaud VS code for its straight and logical thinking on the matter.
But then after looking into it and understanding the problem and more importantly, the rationalle for the solution, it makes perfect sense for doc strings / block quotes to be the same colour as other comments...
But doc strings are not comments, they have very different purpose. And even if some people abuse multiline strings for commenting the code, it doesn't excuse rendering them the same way.
Hey everyone, we will revert for now to the old behavior we had and once @aeschli is back he can drive the discussion going forward.
i do not support changing back.
At first i was "surprised" and though that i had some error with my linter or vs code configuration.
But then after looking into it and understanding the problem and more importantly, the rationalle for the solution, it makes perfect sense for doc strings / block quotes to be the same colour as other comments...
In fact, i always found it rather odd that block comments were a different colour to other comments.
So the correction imposed is actually correcting something that had historically always been incorrecy & i applaud VS code for its straight and logical thinking on the matter.
You are entitled to your opinion. But it has now been explained by many people why doc-strings are not comments, and why this conclusion is absolutely clear and objective from reading the python style guide, and understanding the design, implementation, and behaviour of Python.
The vast majority of people in the previous PR and the mountain of issues that have been created around this, also agree that treating doc-strings as comments is incorrect. This is a community based project, and therefore they should yield to the prevailing opinion of the community.
I do not applaud them, because they made a illogical decision, with no clear reasoning behind it or why they think it "makes sense". And they did it without consulting the community at all, leaving many confused and deeply frustrated. Now, even with a huge amount of support to revert to the previous correct behaviour, it is taking forever.
it is absolutely logical for comments to all be on one colour. Multicoloured coments are a distraction from the code. I was also surprised at first, but after realising the simple rationalle, it makes perfect sense irrespective of what luddites or others with legacy code have to say.
Progress is forwards and just because we were doing things incorractly in the past, does not mean we should not do them properly in the future.
Single colour comments are an excellent idea.
agreed. i would think that providing users with a choice (check-box) of multicoloured comments would keep python 100% of the universe happy.
it is absolutely logical for comments to all be on one colour. Multicoloured coments are a distraction from the code. I was also surprised at first, but after realising the simple rationalle, it makes perfect sense irrespective of what luddites or others with legacy code have to say.
Progress is forwards and just because we were doing things incorractly in the past, does not mean we should not do them properly in the future.
Single colour comments are an excellent idea.
You're either ignoring what has been said, or you're misunderstanding the problem. The point, as has been explained very clearly numerous times now, is that doc-strings are not comments. Which is why your statements do not make much sense at all and don't have any reasonable rationale behind them. This is why almost everyone agrees the old behaviour is better.
You are entitled to your opinion, as i've said, but you're making very strong statements that are founded on fundamentally incorrect idea.
I would agree that allowing for a choice is absolutely fine. But the problem with the original PR was that it was forced upon us without choice, and the majority of the community disagreed with it.
Lets make it abundantly clear. Anything that classify as "notes for humans to read" and "does not affect the code itself" is essentially a comment. And a doc string falls exactly into that category irrespective of what you have incorrectly asserted.
Many users are quite comfortable in seeing these in the same colour as they have the same impact on the code (None).
In fact, i actually enjoy the docstring being in the same colour as the rest of the comments. I like colours to be reserved for keywords and other code types that have an impact on the behaviour of the code.
So "colourful comments" (including doc strings) should be an optional extra for people, like yourself, who vehimently care for such a feature. This would keep everybody happy.
Less is more.
Furthermore, if you can show me meaningfull cases where doc strings impact the actual workings of the code, then i will accept that they should be colourful. Otherwise they should not.
is essentially a comment
making a different part of your sentence bold makes it clear that even by your standards, docstrings are not identical to comments. They are indeed similar and docstrings can in certain cases or definitions be considered comments, but they are not identical.
Also, calling people who disagree with you "luddites" etc, is not a helpful argument...
Lets make it abundantly clear. Anything that classify as "notes for humans to read" and "does not affect the code itself" is essentially a comment. And a doc string falls exactly into that category irrespective of what you have incorrectly asserted.
(I think this has also been mentioned multiple times) Docstrings, as defined in python glossary, is a language feature of python, and is treated by the interpreter differently. Specifically, __doc__ of the function/class/module object will be populated, and is available for read/write during runtime. You have no way to access the "comment string" in runtime, except for code inspection plus manual parsing.
Another reason I'm against your opinion is that "notes for humans to read" are too general. For languages that cannot distinguish, what you said above is okay. However python provides the infrastructure to separate "notes for users" (docstrings) and "notes for developers" (comments), and I think this alone can serve as a sufficient reason to render them differently. (Yet I do admit that maybe we should differentiate plain strings and docstrings, but this is another story which requires further discussion)
In fact, i actually enjoy the docstring being in the same colour as the rest of the comments.
Then you can configure it yourself, just like in the current workaround. And It seems a consensus that vscode should provide a better way of allowing people to configure it.
However, as a widely used tool like vscode, any change to the default behaviour that can majorly impact UX should be carefully reviewed, instead of directly enforcing the preference of some to the rest. If the community agrees with the change, then it is (even so, we should find some way to minimize UX impact). Otherwise we'd better stick to the old behaviour.
Furthermore, if you can show me meaningfull cases where doc strings impact the actual workings of the code,
As said above, docstrings natively affect dunder attributes of specific objects, and thus you're wrong from the very beginning with the assertion that docstring "does not affect the code itself". You don't use it does not mean everyone doesn't, especially when it's a native feature. (If it's indeed useless, "docstring" will never be introduced in python)
One use case that I encounter at times is auto doc generation. One can enumerate functions/classes under a module and retrieve the __doc__ to build documentation in rst/html/... etc. Maybe you would say this is still "notes for humans to read", but you cannot retrieve other "notes" easily.
Furthermore, if you can show me meaningfull cases where doc strings impact the actual workings of the code, then i will accept that they should be colourful. Otherwise they should not.
Introducing autodox, a package that generates documentation using type annotations and docstrings. This uses the __doc__ language feature of Python explicitly, so the lack of a docstring results in a lack of documentation.
