HLSL goal statement and core priorities #504
Conversation
This seeks to codify some high-level principles for guiding HLSL's design.
docs/DesignConsiderations.md
Outdated
| ### The Zen of Python is pretty great | ||
|
|
||
| While not all of Python's design decisions are applicable to HLSL many of their | ||
| design principles apply broadly to programming language design. | ||
|
|
||
| [PEP 20 - The Zen of Python](https://peps.python.org/pep-0020/) has a bunch of | ||
| deeply relevant pithy sayings which are a great set of guidelines to help shape | ||
| programming language design, and we should embrace the wisdom of others. |
There was a problem hiding this comment.
This has a lot of overlap with "We do not exist in a vacuum", and I think it'd make sense to combine them. I also don't think we necessarily need to repeat the zen of python's pithy statements here, but I do think that pointing to them and stating that we're broadly aligned with the values they convey makes sense.
Maybe something along the lines of the following would work:
### We do not exist in a vacuum
Many of the problems we're solving are not unique to HLSL. We should always look
to other languages, tools, and ecosystems as we consider how to evolve our own.
Consider python's ["The Zen of Python"](https://peps.python.org/pep-0020/) -
while Python's particular design decisions aren't always applicable to HLSL
many of their principles apply broadly to programming language design. We
should embrace their wisdom where it applies to us.
There was a problem hiding this comment.
I have had a lot of negative experiences that resulted from pithy statements that were said to be guidelines being used to push back on completed work and force it to be redone. I can think of several ways these statements could result in that. I don't want to fall into that pitfall again.
If the intent is not to use these to push back against proposed changes, then I would like to see in writing that is what "guidelines" means. That it guides your initial intents, but someone should not need to defend why a change violates a "guideline" in a way that a reviewer understands it. If the intent is that they be used this way, then I have a lot of notes.
I agree with Justin that it's best to not list these here wholesale. If we are doing that, let's make them our own with paragraphs instead of 3 word phrases. These were written to guide the consideration of "What would Guido do?" and so they have a lot of unwritten assumptions here that we do not have and even if we knew all the assumptions that Python developers have with these, I don't think we would have them all the same.
docs/DesignConsiderations.md
Outdated
| HLSL can empower them to be more productive and creative. HLSL inherits a lot of | ||
| sharp edges both from its history and C++; we strive to reduce those cases. | ||
|
|
||
| ### The Zen of Python is pretty great |
There was a problem hiding this comment.
I personally like the inclusion of this, but I remember it being contentious in a call we had. Specifically, lots of discussion over "what is a rule vs a guiding opinion". I think the special cases line was a particularly discussed point.
Since we are trying to set goals and priorities for the team/language it would be good to make sure the folks who had reservations about this inclusion are happy with the final result.
There was a problem hiding this comment.
I feel really strongly about the python guidelines going in or even just being referenced without specific modifications. They serve a good purpose in Python and the idea of them is fine, but I don't think HLSL is similar enough to adopt them wholesale without modifications or clarifications. If these go in and they are used to litigate against design decisions, I'm going to be very disappointed. If they are able to be so used, I don't think they are "guidelines".
docs/DesignConsiderations.md
Outdated
| ### The Zen of Python is pretty great | ||
|
|
||
| While not all of Python's design decisions are applicable to HLSL many of their | ||
| design principles apply broadly to programming language design. | ||
|
|
||
| [PEP 20 - The Zen of Python](https://peps.python.org/pep-0020/) has a bunch of | ||
| deeply relevant pithy sayings which are a great set of guidelines to help shape | ||
| programming language design, and we should embrace the wisdom of others. |
There was a problem hiding this comment.
I have had a lot of negative experiences that resulted from pithy statements that were said to be guidelines being used to push back on completed work and force it to be redone. I can think of several ways these statements could result in that. I don't want to fall into that pitfall again.
If the intent is not to use these to push back against proposed changes, then I would like to see in writing that is what "guidelines" means. That it guides your initial intents, but someone should not need to defend why a change violates a "guideline" in a way that a reviewer understands it. If the intent is that they be used this way, then I have a lot of notes.
I agree with Justin that it's best to not list these here wholesale. If we are doing that, let's make them our own with paragraphs instead of 3 word phrases. These were written to guide the consideration of "What would Guido do?" and so they have a lot of unwritten assumptions here that we do not have and even if we knew all the assumptions that Python developers have with these, I don't think we would have them all the same.
docs/DesignConsiderations.md
Outdated
| > Simple is better than complex. | ||
| > Complex is better than complicated. | ||
| > Flat is better than nested. | ||
| > Sparse is better than dense. |
There was a problem hiding this comment.
These seem to be a set in my mind in that they all follow the same sentence structure. They go from extremely broad and indisputable as written to the point of being equivalent to "do good things", which isn't that helpful, to very specific and I'm not sure the utility of. What flatness are we referring to? Presumably to gravitate away from builtin types with multiple levels of subtypes. Sparse versus dense I really don't know what is in reference to. Are these applicable to HLSL?
Explicit is better than implicit is the kind of thing that could be used to beat down a change a reviewer dislikes for other reasons while ostensibly being founded in these guidelines. We often have default parameters. Those are implicit. We often have implicit conversions.
There was a problem hiding this comment.
Without replying on the rest of your comment which does deserve discussion, I'm going to risk a bit of a small tangent
Those are implicit. We often have implicit conversions.
I personally think HLSL leans too implicit but I think the more important thing to call out is that previous decisions shouldn't bind future design decisions (at least not without considering overal design tradeoffs). Just because we have a lot of implicitness today that doesn't mean we can't state explicitness as a design goal for the future
| least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). | ||
|
|
||
| For example, adopting C++'s best-match algorithm for overload resolution aligns | ||
| behavior with C++ user expectations. |
There was a problem hiding this comment.
All of HLSL users are also HLSL users. I'm worried that there is no mention of being least astonishing in the context of existing HLSL here. We got significant pushback from some of the C++ features we added. That doesn't mean they were a mistake and we should never bring the languages closer together. I think we need to be thoughtful and cautious about it. To balance what people expect from HLSL versus what they expect from C++. In particular, I'm concerned about extending features in the areas where HLSL differs from C++. The way this is written, we should definitely follow C++ even for a small feature that extends HLSL concepts and ignore how HLSL did them. I think that would be the most astonishing to users and the uglier than continuing how HLSL has done things. That doesn't mean we can't reconsider these approaches, but I'm opposed to special cases that differ from how the rest of HLSL works because it works that way in C++.
As an incomplete example, if we were to extend constant buffers without revising the way they are represented, I think that we shouldn't innovate in their representation even though no one is really fond of that representation.
docs/DesignConsiderations.md
Outdated
| > Sparse is better than dense. | ||
| > Readability counts. | ||
| > Special cases aren't special enough to break the rules. | ||
| > Although practicality beats purity. |
There was a problem hiding this comment.
This is my biggest concern. As I mentioned above, HLSL has eccentricities that might be considered special cases. How we modify those going forward is a big concern for me. In our latest release, we removed several types from being usable with Typed Buffers. That arguably made an already special case even more special. I don't think that was a mistake, but I couldn't give a good response to why this doesn't violate this guideline.
I acknowledge that the practicality line opens a gap for special cases for special cases, but gives no guidelines to when this can be ignored. Given how easily this could become a point of contention, I think we need more information here. The pithy statements are insufficient.
docs/DesignConsiderations.md
Outdated
| > Special cases aren't special enough to break the rules. | ||
| > Although practicality beats purity. | ||
| > Errors should never pass silently. | ||
| > Unless explicitly silenced. |
There was a problem hiding this comment.
This feels either like the result of a rule about how these guidelines were written or some kind of in-joke. It really doesn't flow for me. It should be one bullet.
docs/DesignConsiderations.md
Outdated
| > Unless explicitly silenced. | ||
| > In the face of ambiguity, refuse the temptation to guess. | ||
| > There should be one-- and preferably only one --obvious way to do it. | ||
| > Although that way may not be obvious at first unless you're Dutch. |
There was a problem hiding this comment.
Again, what?!? Is this a joke? A hagiography? It injects unneeded confusion.
docs/DesignConsiderations.md
Outdated
| > Now is better than never. | ||
| > Although never is often better than *right* now. | ||
| > If the implementation is hard to explain, it's a bad idea. | ||
| > If the implementation is easy to explain, it may be a good idea. |
There was a problem hiding this comment.
I think this overlaps with and is far superior to the special case language. How hard it is to write the documentation can illuminate when a special case is particularly harmful and when it is preferrable. The example I gave about restricting Typed Buffer types further making something even more special is saved by how much easier it makes writing the documentation.
docs/DesignConsiderations.md
Outdated
| > Although never is often better than *right* now. | ||
| > If the implementation is hard to explain, it's a bad idea. | ||
| > If the implementation is easy to explain, it may be a good idea. | ||
| > Namespaces are one honking great idea -- let's do more of those! |
There was a problem hiding this comment.
Too specific. I have nothing against namespaces, but the other guidelines are so high level, they don't deserve this intense an endorsement.
Co-authored-by: Justin Bogner <[email protected]>
Co-authored-by: Justin Bogner <[email protected]>
Co-authored-by: Farzon Lotfi <[email protected]>
This is a minor update to the Design Considerations documentation to include a goal statement to help shape HLSL's future, and some core priorities that will be used to help evaluate language proposals and directions.