[Building a Cipher] Introduction to code comment seems to be out of sequence

[huyenltnguyen]

Description

In the Building a Cipher project, comment is first mentioned in step 51:

After that, you'll see an error appear in the terminal. As a temporary fix, comment out the caesar() call.

But in step 59, we actually introduce comment and its syntax:

When coding, readability is key. Comments serve as effective notes, explaining the logic behind your code. [...]

In Python, you can write a comment using a #. Anything that comes after the # won't be executed.

Links

• https://www.freecodecamp.org/learn/scientific-computing-with-python/learn-string-manipulation-by-building-a-cipher/step-51
• https://www.freecodecamp.org/learn/scientific-computing-with-python/learn-string-manipulation-by-building-a-cipher/step-59

Suggestion

In step 51, we introduce function parameters, so I think mentioning comment here would be a little overwhelming. I think the comment introduction should either be moved to an earlier challenge or kept in step 59.

If we move the comment introduction to an earlier challenge, step 51 can be kept as-is.

But if we keep comment introduction in step 59, we should update step 51. Instead of asking the users to comment out the code, I wonder if we could ask them to remove the line entirely (though the code is added in step 50, so it's probably a little odd to immediately remove it in the next step).

[zairahira]

This does seems to be out of sequence.
I would suggest to not comment out caesar() in step 51 and let the exception be(the resolution is there in the coming steps).

This part of the instruction can be updated from:

After that, you'll see an error appear in the terminal. As a temporary fix, comment out the caesar() call.

to:

After that, you'll see an error appear in the terminal. You'll work on the resolution in the coming steps.

[Dario-DC]

If we don't ask to comment out the function call in step 51 and tell the campers they will work on fixing the error in the next steps, it would be logic to address the error in the console (TypeError: caesar() missing 2 required positional arguments: 'message' and 'offset') and require to pass the two positional arguments to the function call in step 52.

But then the function will seem to work fine, although it's still using the text and shift variable inside its body instead of the function parameters.

The alternative is to ignore the TypeError in the console for step 52, and address it directly in step 53. For that we should simply keep the function call instead of commenting it out and there is no need to swap the step order.

Honestly, I don't like particularly any of these options.