hsutter
[SUGGESTION] Demo-Documentation
The "Where's the Documentation" section states "I'm not posting much documentation because that would imply this project is intended for others to use — if it someday becomes ready for that, I'll post more docs."
A primary long-term goal of this experiment seems to be making modern, idiomatic C++ approachable to people learning C++ for the first time. i.e, people who are unaware of the long-history and developments of C++ could learn, and understand, beyond just superficially, the semantics of cpp2.
Here I argue that building demo-documentation as this experiment is developed grounds one in this long-term goal, so that one has real measurements (namely, the length of the demo-documentation) of this project's performance relative to this goal, thus creating a healthy feedback-loop rather than a dreamt ideal of the far future.
If one discovered (in the distant future) that to teach a learner a truly accurate (free of edge-cases) model of the semantics of cpp2, one needed to refer back to the very things one wished to remove from cpp1, clearly that would be what the kids are calling an "epic fail."
Peers often teach concepts better than professors, because the peer knows what it's like to not understand that concept, whereas the professor long-ago forgot what it was ever like not to understand. Therefore, I argue it would be wise for an expert who's developing something with the goal of learnability to go beyond his own theoretical perception of learnability and create concrete (demo-)documentation, to verify that the perceived simplicity isn't illusory, and one truly doesn't ever need to mention the cpp entities omitted in cpp2.
Additionally, this could attract more eyes to this project from people who aren't experts of modern cpp -- especially teachers -- who may have found modern cpp too daunting to teach in the past, but who after seeing a non-expert-oriented documentation, might become excited about the future of this experiment and about teaching it in the future.
Of course time is limited and it may simply be too low on the priority list, which is fair. Here I only argue that "documentation would imply this project is intended for others to use" is, imo, not a good enough reason to exclude documentation, as one could put a disclaimer in the documentation that this project is not intended for others to use.
I'm relatively young programmer. Industry is moving fast and requires fast engineering. Learning all the "how-to"s to write proper modern CPP code is simply infeasible and bothersome and takes up too much extra syntax (which in turn makes it hard to read and maintain). For new engineers' other languages are much more appealing despite being slower due to safety and simplicity. This project can quickly bring CPP to level of other languages while having advantages of performance and vast ecosystem support.
I for one would gladly start using this early alpha experimental project instead of dealing with all the weird keywords and complex best practices of current CPP.
I realize this is basically an experiment. But for this experiment to be successful other devs should get their hands on it as well and for that documentation is necessary. I think this project has HUGE potential, please do not allow its massive potential to be crippled by lack of documentation
This is something I am trying to prepare. I am trying to write cpp2 app that compiles markdown documentation as tests and that will generate html docs.
It is going slow as I needed to contribute to the cppfront to be able to implement basic features.
@hsutter is back from Kona meeting and I believe we will push cppfront forward (there are several PRs already waiting).
@hsutter is back from Kona meeting and I believe we will push cppfront forward (there are several PRs already waiting).
Remember https://github.com/hsutter/cppfront/pull/106#issuecomment-1299365791.
Personally, i do agree that some examples & explanations would be great. Even though this project is an experiment, a measure of documentation is necessary to help others understand the value of the experiment as well as the design decisions behind it, especially considering that there is an increase in interest in this project from the C++ community.
Besides, who knows where cppfront will go in the future.
Also, @filipsajdak let us know if you need any assistance with that test app you mentioned, I would be happy to contribute when I have some free time later this week.
I fully agree that this project needs documentation. To be more precise, I would say that C++2 needs semantics (or specification) which is given in terms of its own basic concepts, and not in terms of the current C++ standard wording. Why?
- For humans that do not already know C++, so that they can understand C++2 without understanding C++ first.
- For tools doing static analysis and formal verification, so that they do not have to understand full C++ in order to do the analysis/verification.
- Because we usually do not explain a language by translating its constructs into assembly, but by explaining the high-level concepts. The fact that a language (say, C) have a support for inline assembly does not mean that everything had to be explained in terms of assembly. Similarly, the fact that C++2 links with C++ does not mean that everything has to be explained in terms with C++.
To elaborate on the second point. Currently, there is almost no support for formal verification of C++, and virtually no support for reasoning type-polymorphic code (templates). But if C++2 has simple semantics, then it is possible to formally reason about polymorphic code without building a verification tool for the big/"old" C++.
Practically, I would like to give the "pure" fragment of C++2 a formal/mathematical semantics using the K framework, from which a formal verification tool can be easily derived. I have already started, but it is hard to do without having an informal/english semantics first.
I strongly agree with user documentation... for example, I have a 10-page "Cpp2 for Cpp1 programmers" guide fully written, because to me a core adoption metric is "can a programmer who knows today's C++ learn 'syntax 2' over a long lunch, and start writing productive code that afternoon?" I think the answer has to be Yes for Cpp2 to reach my goals of being clearly still C++ and being easily adoptable by C++ programmers, and I don't think any of the other experiments or products aiming to improve C++ are close to reaching such a high bar goal. So, yes, docs are important to me not just for their own usefulness but also as a measurable success metric.
I've chosen not to post that 10-page guide (or the 120-page detailed design document) until there's a more complete syntax 2 implementation in cppfront that's more usable (e.g., has classes), and then teaching materials become appropriate... two drawbacks of posting documentation too early are:
- while things are incomplete, the documentation can't show the whole thing as it's intended to be (e.g., most of the examples in that 10-page guide don't compile yet because they use classes which aren't implemented yet in cppfront)
- while things are changing, keeping the documentation in sync is an overhead cost
Once more of the implementation is there, if the experiment is still working out, docs will definitely be coming.
Thanks for the interest!
