Before we truly begin here...Remember this?

[mburns08109]

https://github.com/twinbasic/twinbasic/discussions/610

I'm not so certain that this discussion ever reached anything like a final consensus...so much as it just seemed to peter out and get bypassed by events.

This seems very much like an opportune moment - before the deeper work of the Lang-spec wiki actually begins - to revisit/complete that discussion - even if that end is purely going to be Wayne saying "NO, it's going to be THIS way..." as opposed to an agreed consensus from those of whom are "deeply participating" (which can be read as "paying customers" by those of a more cynical bent) to date.

So, perhaps a summation of that lengthy discussion is in order as a first step?

[mburns08109]

Recap: @bcloithier's last posting of points was:

Draft 3: Trying to incorporate what has came up in discussions (not just here but also other discussions/issues). I also think a different format might be more helpful in expressing the goals more clearly. Swapped the 5th point with 6th point because I think it flows better and corresponds more to how often we have to deal with the each point.

Again, discuss.

Backward compatibility trumps everything
twinBASIC was born out of the desire to provide an upgrade path for Visual Basic 6 and VBA. We fully believe that breaking compatibility, even to upgrade something that was working is always risky and nobody should be forced to rewrite software just to gain new features. As a consequence, twinBASIC will always remain fully compatible with VB6, VBA and future versions of twinBASIC. Any new features introduced must respect that.

Community is essential
Programming language is never just merely a language. A healthy programming language is one with a healthy ecosystem and to achieve this, we aim to make it easy as possible to share and contribute code and engage with other users.

Solving problems is the point
twinBASIC, like Visual Basic, is oriented toward helping the users focus on the business problem, rather than the implementation details. To that end, twinBASIC will try to provide good defaults and allow the user to work at the high level. However, the user is free to go lower where it is necessary for the solution.

Readable code is better than terse code
Because code is usually read more often, and will be read at different points, we want to encourage and promote writing readable code from the first-go. The ideal readable code is the one where the user achieves the same mental state as the writer had with minimal effort.

Transparency rocks
Code that says what it does is far preferable to clever hacks or implicit behaviors. twinBASIC will provide tools to help make implicit explicit and make it easy for users to see the actual behavior. Ideally, the users should never be astonished even if the code is originally gnarly.

Consistency matters
A consistent language is easier to learn and predict. Furthermore, consistent language makes sharing easier. To that end, twinBASIC will strive for maximum consistency in its syntax & features and make it easy for users to follow a coding style. However, readability takes priority over consistency.

One way is better than several ways
twinBASIC aims to push forward but in considering new features, we must take care to assess what already exists, whether there is a legitimate need that is not already met, whether it can be best done by tweaking existing features, and once exhausted, assess how new feature will fit in the overall language and provides a genuine new way that is clear and intuitive to the users. We want to minimize synonyms and different ways of saying the same thing unless it can be shown that readability and clarity will trump. By having only one way of doing, we also make the language easier to use, read and understand.

Refactoring and testing should be natural
twinBASIC exists expressly to support graceful upgrade of long-lived codebases without forcing a rewrite. Requirements may change but the users must be able to answer the questions on the impact and be able to make changes to the codebase without any fear of breaking the codebase or missing details. Testing should be easy and can be applied even to an existing project, which will in turn directly aid refactoring and proving that the software did not change in unexpected ways.

Documentation is important
In other languages, documentation is usually an afterthought. twinBASIC will make it easy as possible for users to write documentation and share it with other users.

Shipping will be tripping
twinBASIC will not come with runtime library, a virtual machine, a framework. It will come as it is to the end users' computer, in most compact form possible. It will not demand complex registration or installation process. xcopy deployment is the pinnacle.

BUT...he later added:

Just to note that I've had a draft for last few days but hadn't gotten to a point where it's an improvement over the draft 3. Sorry for the delay. Hopefully, I'll get to it this weekend.

[WaynePhillipsEA]

I'm not opposed to finalizing the guiding principles, but we should bear in mind that this repo is for documenting the language spec, not for language design discussions.

[mburns08109]

I'm not opposed to finalizing the guiding principles, but we should bear in mind that this repo is for documenting the language spec, not for language design discussions.

I have no problem with that - we can have any additional discussion back in the original topic as far as I'm concerned, but I would think that the design principles would be included somewhere in the language spec document...would it not?

[WaynePhillipsEA]

I'm not opposed to finalizing the guiding principles, but we should bear in mind that this repo is for documenting the language spec, not for language design discussions.

I have no problem with that - we can have any additional discussion back in the original topic as far as I'm concerned, but I would think that the design principles would be included somewhere in the language spec document...would it not?

Sure, we'll probably link to the guiding principles, but I would expect it to be defined in a lang-design repo. My main concern was that the guiding principles not being finalized doesn't need to halt the start of the lang-spec documentation. If we later need to change something in the lang-spec documentation (e.g. from needing to better conform to the guiding principles), then that is fine and the lang-spec should then be updated to reflect the change, including details of the old syntax.

[EduardoVB]

It is just a comment that I wanted to post somewhere, I'll do it here.

I found that making documentation is also good for finding bugs, and improving some things.
Because you need to explain how things work, and what would happen in every case (every input), and sometimes you realize that your program is not prepared to handle some cases.
You discover situations that you never thought about.
Also, when you have to explain things to other people, you need first to build the image in your mind of how the thing works, and sometimes you realize that what you did needs to be refactored in some way, because you realize it is not right according to what you are explaining (or realize it should be).
Things that sometimes we overlook when developing, or realized but left for the future and then forgot.
That happened to me when I made the BSPrinter documentation.

[mansellan]

Now that we have lang-design, this should probably move there (and maybe be closed, as it's just a reminder to another discussion)