Wip-Implement_new_Concept_Exercise-basics_379

[vaeng]

First raw draft for a new exercise to start the basic concept

[github-actions]

Hello. Thanks for opening a PR on Exercism. We are currently in a phase of our journey where we have paused community contributions to allow us to take a breather and redesign our community model. You can learn more in this blog post. As such, all issues and PRs in this repository are being automatically closed.

That doesn't mean we're not interested in your ideas, or that if you're stuck on something we don't want to help. The best place to discuss things is with our community on the Exercism Community Forum. You can use this link to copy this into a new topic there.

---

Note: If this PR has been pre-approved, please link back to this PR on the forum thread and a maintainer or staff member will reopen it.

[siebenschlaefer]

about.md

This document is a wild mix of things. It's mostly about methods, but also mentions variables, values, classes, namespaces, file organization, and comments. I can't see how some "concept" is introduced and explained. As a beginner this text would rather confuse me, I don't think I would learn anything from it.

This is mostly about methods, right? ("We are focusing on on methods ...")
Personally I would prefer the official term "member functions" but that's just nitpicking.

The first section is titled "variables and values" but then talks about parameters and the initialization of variables, there's nothing about values.

The third section is titled "Methods" but instead of explaining what a method is, or how it's different from a free function, it starts with the detail that it can be called without a "prefix" (a term not previously introduced).
It then (correctly) mentions that methods differ by return type, name, number of parameters and their types. But it also puts "names" into that list which is IMHO wrong, and doesn't mention things like cv-classifiers.
(If you don't want to go into these more advanced details add some handwaving "etc." somewhere and explain it later or in a different concept.)
The code snippet looks like a free function, not a method.

The fourth paragraph is titled "A word on classes".
It start with the organization of code into .h and .cpp files, contains a very short high-level sentence about how the definition oa class can be read and dives directly into an example with a namespace (without explaining that in any way). Do you need namespaces at all in this document?
It very briefly explains the difference between static and non-static member functions but then says that in the example each bike has its own ID. How can that be without member variables?

The sixth paragraph is about "Invoking methods" but then uses the terms "function" and "class method". That's a little bit confusing.
Wouldn't the second sentence about functions and methods without arguments better fit into the third section ("Methods")?
There's a using namespace directive in the code snippet. Please avoid them, too many beginners learn to always add a using namespace std; in their code which imports all the symbols of that namespace, can lead to quite tricky issues, and it takes effort to convince them that this is a bad habit in general.
There's an operator new in the code snippet. That is syntactically wrong (the result would be a pointer) but "naked new" is something that is actively discouraged by most experts. The correct and idiomatic alternative would be either ShigeruSpecial bike; or auto bike = ShigeruSpecial();

And a few mixed notes:

• Markdown files here on the Exercism repositories should contain one sentence per line. That doesn't affect how the text is rendered but it makes it easier to maintain these files.
• I'm not a native English speaker but I think there are some grammatical errors, for example singular forms of verbs where a plural form is needed, or incorrect duplications of words ("on on").
• Please use expressive variable names. That makes it so much easier to understand code. i and j might be fine for index or counting variables in (nested) loops but in all other contexts I recommend names that help the reader.

instructions.md

This document doesn't look bad. I'm just not sure why we would want to use methods (a.k.a. member functions) for those tasks. There's no state, these should rather be free functions instead.

There's a stray backtick in the code snippets for the 3rd and 4th task.

Is the "spend" in the heading of the 4th task correct, shouldn't it be "spent"? (non-native English speaker here)

hints.md

Doesn't look bad either. But wouldn't it make sense to introduce something like return in the text document instead of a hint?

And again, "spend" vs. "spent" (strangely there is a "spent" in the final paragraph.)

design.md

This document talks about many objectives that were never explained in text or required by the concept exercise.

---

Overall this is a mixed bag. The concept exercise is quite OK although I would strongly prefer not to use member functions for these tasks. But I find the the text (about.md and introduction.md) pretty underwhelming. I cannot imagine that they will help somebody learning the language. And that's in my opinion the biggest issue.
Teaching C++ by text is really hard. Back when I had access to an Amazon Prime account I read many free introductory books on C++ that were independently published. Not one of them was good or even just acceptable, they all contained lots of mistakes, were confusing, and just bad text books.

The only free tutorial on C++ that is widely recommended in the C++ community is LearnCpp.com. In my opinion we should align our concepts to that because it manages to provide some sort of "path", and we can reference it.

[vaeng]

Thank you for the time to review my suggestions. I think you are completely correct @siebenschlaefer.
It is too much for one concept. I tried to build upon the railing that was laid out in: #379.

I would rather have functions (returns, invoking) and values (initialization and some algebra) in one exercise and add classes later.

LearnCpp.com has similar goals, so I think it is a good guideline for teaching cpp, but I do not want to blatantly copy their work.

[vaeng]

I wasn't sure how much I should deviate from the structure so I left it in. I was wondering how the header is displayed to the user on the website. Is it possible to not show the header? Some solutions have inlined function definitions in the header, but that should not be the first thing a new learner should be confronted with, right?

I uploaded .h and .cpp files without the class, would that be possible, or should I skip the header file completely? HelloWorld does not and is even more "basic".