Inconsistency in headers provided

[joshgoebel]

Most exercises provide at least the header to get you started (so you know what API you are implementing)... but some give you nothing. Example: circular_buffer... this makes it much harder to get started.

Is this somehow intentional? Could we agree on what amount of boilerplate exercises should start with and then would PRs be welcome here?

[ryanplusplus]

When we've discussed this in the past, the goal was to use empty headers as part of the exercise. Of course, the goal is to create a learning opportunity, not put up a brick wall. I don't mentor the C track so I don't have a good feel for where people are struggling and it's entirely possible that we've missed the mark in what we provide for some of the exercises.

PRs are welcome.

[wolf99]

I think we previously discussed if we should add Stubb's and decided only to have them for the earlier exercises.

Open to discuss the idea again though.

I raised the same concern on the PR and Josh validly pointed out that this policy is not apparent in the implementation.

IIRC the main stumbling block that we had before was that for some exercises providing the stubs "gave the game away". With concepts starting Ng to be created perhaps this concern is less of an issue?

[joshgoebel]

providing the stubs "gave the game away".

I feel like I didn't include stubs where the stubs were the whole exercise... (resistor enums, etc)... but most of the time it's just the headers and then you still have to implement the actual algorithm... so I guess the question is how hard are we trying to make it...

[bobahop]

Having done 44 solutions myself and having mentored 200+ solutions, I can't say I recall the lack of forward declarations for some exercises to have been much of a problem for myself or others. I may have had a very few students express they had difficulty, but I don't remember any specifically. When lacking forward declarations, my own approach has been to look at the tests to see what function signature(s) they expect and take it from there. It may be a bit challenging to have to do that, but it's also rewarding when, hey! I figured it out! 😄

[joshgoebel]

I can't say I recall the lack of forward declarations for some exercises to have been much of a problem for myself or others

I can only say I found it a problem - perhaps it was more the inconsistency though? I was/am still a bit hazy on the difference between things like *, **, [], [][] or what not... and just looking at the tests (which does work well in many other languages) I sometimes still found it challenging to parse those differences.

Having some/most exercises I could jump right into and then only some where I hit the no headers wall - friction and frustration. Perhaps if they all forced me to do the work it would have been better (in the long run), at least it wouldn't be inconsistent.

It may be a bit challenging to have to do that, but it's also rewarding

It can be. I just think we need to deal with the inconsistency. Seems like it shouldn't be a coin toss whether a students gets headers or not?

[bobahop]

I think it has to be to be inconsistent, or forward declarations would need to be made (or not made) for all exercises. For some of the very simplest exercises which are most likely to be solved by beginners, it's welcoming to provide forward declarations. Once the exercises get a bit more challenging, even the "Easy" ones, I think it starts being more appropriate to have them stretch a bit by constructing the forward declarations themselves. That wouldn't be a coin toss but a natural progression.

[joshgoebel]

I think it has to be to be inconsistent

We're overloading the word. It can be both. It could be consistent period (always the same) or a consistent policy across the track (as you are about to suggest:)

For some of the very simplest exercises ... it's welcoming to provide forward declarations. Once the exercises get a bit more challenging ... it starts being more appropriate to have them stretch a bit...

This sounds consistent [as a policy] but in my experience this is not how it is now.

• some of the earliest exercises lack headers
• some of the much harder exercises have them

Consistent period or consistent policy, just not randomness. :) Your proposal is reasonable. If we call can agree on policy I could revisit the PR, though it will take a bit longer since now we're adding nuance... perhaps we could do it according to difficulty numbers in the JSON?

[bobahop]

Outside of "Hello World", I'm not sure which exercises should definitely have forward declarations. It probably would be good for the maintainers to identify a small handful of the simplest exercises that should have them. The rest may or may not have them for whatever reason. I don't see taking them away from more difficult exercises just for the sake of consistency, but I think it's reasonable for a small subset of the easiest exercises to have them. I'm thinking five or maybe less.

[bobahop]

Perhaps the declarations for some exercises could be put in the Hints section. That way it wouldn't ruin it for students who want to figure them out for themselves.

[wolf99]

IIRC we previously completed an initiative to have stub headers for all exercises up to a certain point, with none after that point

I don't recall up to which exercise exactly, but it was approximately 1/4 or 1/3 of the way through the track.

I'm guessing more have crept in since then though.

[joshgoebel]

Perhaps the declarations for some exercises could be put in the Hints section.

That's a reasonable compromise I think.

[siebenschlaefer]

Did we come to some sort of agreement here?
I'm willing to make the changes so that we can close this issue.

[wolf99]

Hi @siebenschlaefer
We would welcome PRs with a solution on this.
Several good ideas in the thread here so far.
Picking out some points

• consistency will be key
• will be good to have an overview of the current situation, which exercises have headrrs and which do not, and which order those exercises now come in.

[siebenschlaefer]

These are the exercises (in the order they appear on https://exercism.org/tracks/c/exercises and in config.json) with their difficulty and what the .h file initially contains:

slug	difficulty	initially
hello-world	1	stubs with comments
armstrong-numbers	1	stubs
resistor-color	1	no stubs, only a skeleton enum
isogram	1	stubs
hamming	2	stubs
grains	1	stubs
difference-of-squares	1	stubs
square-root	4	no stubs
grade-school	3	no stubs, only constants and structs
binary-search	2	stubs
rational-numbers	5	no stubs
circular-buffer	3	no stubs
list-ops	3	stubs with comments
pythagorean-triplet	4	no stubs
saddle-points	4	no stubs
allergies	4	stubs
phone-number	4	stubs
clock	2	stubs
sieve	2	stubs with comments
robot-simulator	2	stubs
pascals-triangle	1	stubs
binary	1	stubs
queen-attack	1	stubs
linked-list	4	stubs with comments
darts	1	no stubs
resistor-color-duo	1	no stubs
resistor-color-trio	1	no stubs
acronym	1	stubs
gigasecond	1	stubs
space-age	1	stubs
pangram	3	stubs
word-count	3	stubs with comments
rail-fence-cipher	4	stubs
matching-brackets	5	stubs
nucleotide-count	2	stubs
rna-transcription	2	stubs
secret-handshake	3	stubs
meetup	4	stubs
pig-latin	4	stubs
leap	1	stubs
two-fer	1	stubs
beer-song	2	stubs
raindrops	2	stubs
roman-numerals	3	stubs
wordy	4	stubs
bob	5	stubs
complex-numbers	2	stubs
sum-of-multiples	4	stubs
two-bucket	6	stubs
anagram	5	stubs with comments
binary-search-tree	6	stubs
say	6	stubs
etl	2	stubs
series	2	stubs with comments
diamond	3	stubs
minesweeper	3	stubs
run-length-encoding	4	stubs
atbash-cipher	5	stubs
crypto-square	6	stubs
react	10	stubs, partially with comments
prime-factors	2	stubs
nth-prime	4	stubs
perfect-numbers	1	no stubs, only an enum
triangle	1	no stubs, only a struct
collatz-conjecture	2	stubs
luhn	2	stubs
palindrome-products	2	stubs
all-your-base	3	no stubs, only a constant
scrabble-score	4	stubs
sublist	4	stubs
largest-series-product	5	stubs

[siebenschlaefer]

Having looked at them all I agree with @joshgoebel, they are pretty inconsistent.

As a C programmer I really like the exercises that provide stubs with comments. That makes it so much more obvious what I'm supposed to do, and I don't have to dig into the tests to figure that out. I'd suggest doing that for a few more exercises, especially the simpler ones or the ones at the beginning of the list.

But as a mentor I see the value of having the students figure out the functions and involved types for themselves. For example for the resistor-color exercise the students have to understand enums, and I had lots of conversations about which types to use. And for several exercises I regularly have discussions about which parameters and return types should be pointers to const. Providing complete stubs would probably reduce what the students can learn from such an exercise.