ProgrammingWarmups / www.warmups.dev

:rocket: Warmups, for Developers
MIT License
3 stars 4 forks source link

Some exercises possibly teach questionable commenting practices #16

Open mariakimheinert opened 3 years ago

mariakimheinert commented 3 years ago

In some exercises, the user is encouraged to record expected outputs in comments. For example:

W1, E1

# ____: ___

W1, E3

# The program should output:
# Mean: 5.0

W1, E5

# The program should output:
# Mean: 4.0

W2, E1

# TODO: fill in the program's output
# ____: ___
# ____: ___

W3, E1

# TODO: fill in the comment with the correct number
# there are __ email addresses in the file

Though I understand this is a way to interact with the person performing these warmups, I worry that it may be indicating that these are the kinds of comments you want to write in actual source code. I think the warmups should teach users good commenting practices from the very start. These comments are potentially problematic because inputs/outputs often change in a program and writing exact values in comments means that either the programmer must be meticulous about always updating comments (which I've found to be very difficult) or the comments will fall behind the code and quickly become inaccurate/unhelpful (which is almost always what happens to me). Instead, programmers should be encouraged to write more general comments that should remain accurate as long as the logic of the code does not change.

Could there be a better way to interact/pose questions to users without using comments in this way, such as asking for parts of the expected output through a multiple choice question?

DayMath82 commented 3 years ago

Maybe they could teach commenting practices in a future warm-up and clarify that these comments are for the user's interaction?