{"assignment":{"_schema_version":2,"course_id":37,"date_created":"2022-06-28T19:00:00+00:00","date_modified":"2023-08-26T14:03:25.816544+00:00","extra_instructor_files":"","extra_starting_files":"","forked_id":null,"forked_version":null,"hidden":false,"id":938,"instructions":"## Code is Confusing\n\n![Picture of a human looking confused, while a computer looks happy.](intro_comments_confusing_code.png)\n\nCode can be confusing.\nThere's no way around it.\nFiguring out what a program does is often just as hard as writing the code in the first place \u2014 and sometimes harder.\nBad code is so easy to write.\nComments are a way for programmers to understand what a certain piece of code does without having to mentally translate it.\nComments are written explanations embedded directly in the code that explain the code to the reader.\nThe computer does not care about comments when it executes the code, and the system does not even look at the comments.\nThey are only for humans to make code less confusing for other humans.\n\n## Comments in Python\n\n```python example-comments\nprint(\"This line is executed!\")\n\n# All the following lines are valid, because they're comments\n# This line is not executed\n# 1 / 0\n# 5 = a\n```\n\nIn Python, the main way to write comments is to use the \"hash symbol\" (`#`), also known as the \"hashtag,\" \"octothorpe,\" \"number sign,\" or \"pound sign.\" When Python runs your program, it first scans for any hash symbols.\nThose symbols and ALL text that comes after it on the same line are then removed.\nThe only exception to this rule is if a comment is inside of a literal string value.\nOtherwise, comments are always removed from any Python program.\nYou might be familiar with hashtags in social media that use the same 'hash symbol' as Python comments.\nSome example hashtags that you might find interesting are: `#EveryoneCanCode`, `#CSforGood`, `#InclusiveCoding`, and `#CSforSocialJustice`.\n\n## Tracing Comments\n\n```python skipped-lines\nprint(\"First line, first step.\")\n# Skipped line!\nprint(\"Third line, second step.\")\n```\n\nBecause commented code is removed from the program, Python will skip over those lines when running your code.\nThis is one reason why, when tracing your program, the current line and the currently executed step might not be the same.\nIn the program shown here, the second line is commented out, meaning the second step is actually the third line executed!\n\n## Improving Names to Avoid Comments\n\n```python better-names\n# Unclear variable names version\n# Store the current time (42 minutes)\nx = 42\n# Convert to hours, add the offset\ny = x / 60 + .5\n# Print result\nprint(y)\n# ----------------------------------------\n# Clear variable names version\n# Convert the time from minutes to hours, with an offset\nminutes = 42\nhours = minutes/60\noffset = .5\ntime = hours + offset\nprint(time)\n```\n\nComments aren't always necessary.\nSometimes, instead of trying to add additional explanations about code, you should just make the code less confusing.\nFor example, in the code shown here, the first version uses variable names that are vague and confusing.\nBut the second version has better variable names which make it easier to understand the code's purpose.\nThis is especially important as programs get bigger and more complex, where explaining every line has more of a penalty.\n\n## How Many Comments Are Enough?\n\n* Extreme opinion: Comment every line\n* Opposite extreme opinion: Never comment\n* Reasonable middle ground: Comment confusing code\n\nHow many comments should you write?\nOpinions vary, and there's no perfect answer.\nSome people believe you should explain every line.\nSome people believe that comments should never be necessary, since you should just write the code to be clearer.\nA middle stance is to write comments for any code that is unexpected or surprising.\nWhen working with others or for someone, you will want to learn what their expectations are, while also developing your own style.\n\n## Commenting Out\n\n```python commented-out\nminutes = 42\n## Used to be integer division, now float division for correctness\n# hours = minutes//60\nhours = minutes / 60\noffset = .5\ntime = hours + offset\nprint(time)\n```\n\nComments can also be used to temporarily remove code.\nWe call this \"commenting out\" code.\nHowever, permanently removing code using comments (instead of just deleting the code) is generally bad practice.\nIn future courses, you will learn more advanced ways to keep track of code over time.\nBut for now, when you are thinking about how to share code with others, _remove any comments that don't help explain the existing code_.\nIf you are going to comment out code, be sure to leave an additional comment for yourself explaining what that old code was there for.\nRemember, you are going to forget what a program does.\nThe less time spent trying to remember, the better your future life will be.\n\n## Summary\n\n- Comments are used to document and explain code.\n- The hash symbol (`#`) creates a comment in Python, meaning that everything after that symbol will be ignored on the line.\n- Opinions vary on how many comments to put into code, but generally we recommend that you comment on any lines that are confusing.\n- Oftentimes, you can replace a comment by cleaning up variable names to be less confusing.\n- Comments are also sometimes used to temporarily remove code while developing (for example, to try out a new approach), but you should always remember to remove the dead code afterwards.\n\n","ip_ranges":"","name":"1B4) Comments Reading","on_change":"","on_eval":"","on_run":"","owner_id":1,"owner_id__email":"acbart@udel.edu","points":0,"public":true,"reviewed":false,"sample_submissions":[],"settings":"{\n  \"small_layout\": true,\n  \"header\": \"Comments\",\n  \"slides\": \"bakery_intro_comments.pdf\",\n  \"video\": {\n    \"Bart\": \"https://blockpy.cis.udel.edu/videos/bakery_intro_comments-Bart.mp4\",\n    \"Amy\": \"https://blockpy.cis.udel.edu/videos/bakery_intro_comments-Amy.mp4\"\n  },\n  \"youtube\": {\n    \"Bart\": \"hkxAEemC3m4\",\n    \"Amy\": \"FD3nBWlN5zI\"\n  }\n}","starting_code":"","subordinate":true,"tags":[],"type":"reading","url":"bakery_intro_comments_read","version":12},"ip":"216.73.216.157","submission":{"_schema_version":3,"assignment_id":938,"assignment_version":12,"attempts":0,"code":"","correct":false,"course_id":37,"date_created":"2026-05-20T23:50:34.995765+00:00","date_due":"","date_graded":"","date_locked":"","date_modified":"2026-05-20T23:50:34.995765+00:00","date_started":"","date_submitted":"","endpoint":"","extra_files":"","feedback":"","grading_status":"NotReady","id":2037093,"score":0.0,"submission_status":"Started","time_limit":"","url":"submission_url-a806f670-f8d9-4938-9e95-06524d584ed0","user_id":2044772,"user_id__email":"","version":0},"success":true}