{
  "source_file": "0930",
  "source_platform": "Medium",
  "author": "Kurtis Pykes",
  "title_listed": "All You Need to Know about Writing Effective Comments in Your Code",
  "keywords": "代码注释,规范",
  "domain": "数据处理",
  "content_type": "深度技术解析",
  "is_paid_flag": "部分免费/会员墙",
  "url": "https://towardsdatascience.com/all-you-need-to-know-about-writing-effective-comments-in-your-code-41134a5acb60/",
  "publish_date": "2022-05",
  "corpus_stage": "预训练/SFT",
  "notes": "",
  "id": "f8be502f0a93",
  "collected_at": "2026-10-01T23:57:00",
  "title": "All You Need to Know about Writing Effective Comments in Your Code | Towards Data Science",
  "body_markdown": "![Revisit consent button](https://cdn-cookieyes.com/assets/images/revisit.svg)\nWe value your privacy\nWe use cookies to enhance your browsing experience, serve personalised ads or content, and analyse our traffic. By clicking \"Accept All\", you consent to our use of cookies.\nCustomise Reject All Accept All\nCustomise Consent Preferences ![](https://cdn-cookieyes.com/assets/images/close.svg)\nWe use cookies to help you navigate efficiently and perform certain functions. You will find detailed information about all cookies under each consent category below.\nThe cookies that are categorised as \"Necessary\" are stored on your browser as they are essential for enabling the basic functionalities of the site. ... Show more\nNecessaryAlways Active\nNecessary cookies are required to enable the basic features of this site, such as providing secure log-in or adjusting your consent preferences. These cookies do not store any personally identifiable data.\n  * Cookie\nBCTempID\n  * Duration\n10 minutes\n  * Description\nNo description available.\n\n\n  * Cookie\n__cf_bm\n  * Duration\n1 hour\n  * Description\nThis cookie, set by Cloudflare, is used to support Cloudflare Bot Management. \n\n\n  * Cookie\nAWSALBCORS\n  * Duration\n7 days\n  * Description\nAmazon Web Services set this cookie for load balancing.\n\n\n  * Cookie\n_cfuvid\n  * Duration\nsession\n  * Description\nCloudflare sets this cookie to track users across sessions to optimize user experience by maintaining session consistency and providing personalized services\n\n\n  * Cookie\nli_gc\n  * Duration\n6 months\n  * Description\nLinkedin set this cookie for storing visitor's consent regarding using cookies for non-essential purposes.\n\n\n  * Cookie\n__hssrc\n  * Duration\nsession\n  * Description\nThis cookie is set by Hubspot whenever it changes the session cookie. The __hssrc cookie set to 1 indicates that the user has restarted the browser, and if the cookie does not exist, it is assumed to be a new session.\n\n\n  * Cookie\n__hssc\n  * Duration\n1 hour\n  * Description\nHubSpot sets this cookie to keep track of sessions and to determine if HubSpot should increment the session number and timestamps in the __hstc cookie.\n\n\n  * Cookie\nwpEmojiSettingsSupports\n  * Duration\nsession\n  * Description\nWordPress sets this cookie when a user interacts with emojis on a WordPress site. It helps determine if the user's browser can display emojis properly.\n\n\n  * Cookie\nBCSessionID\n  * Duration\n1 year 1 month 4 days\n  * Description\nBlueconic sets this cookie as a unique identifier for the BlueConic profile.\n\n\n  * Cookie\n_octo\n  * Duration\n1 year\n  * Description\nNo description available.\n\n\n  * Cookie\nlogged_in\n  * Duration\n1 year\n  * Description\nNo description available.\n\n\n  * Cookie\n__Secure-YEC\n  * Duration\npast\n  * Description\nYouTube sets this cookie to stores the user's video player preferences using embedded YouTube video\n\n\n  * Cookie\n__eoi\n  * Duration\n6 months\n  * Description\nDescription is currently not available.\n\n\n  * Cookie\nAWSALBTGCORS\n  * Duration\n7 days\n  * Description\nNo description available.\n\n\n  * Cookie\nlogin-status-p\n  * Duration\npast\n  * Description\nDescription is currently not available.\n\n\n  * Cookie\nAWSALBTG\n  * Duration\n7 days\n  * Description\nNo description available.\n\n\n  * Cookie\ncsrf_token\n  * Duration\nsession\n  * Description\nNo description available.\n\n\n  * Cookie\ntoken_v2\n  * Duration\n1 day\n  * Description\nDescription is currently not available.\n\n\n  * Cookie\nD\n  * Duration\n1 year\n  * Description\nDescription is currently not available.\n\n\n  * Cookie\nPHPSESSID\n  * Duration\nsession\n  * Description\nThis cookie is native to PHP applications. The cookie stores and identifies a user's unique session ID to manage user sessions on the website. The cookie is a session cookie and will be deleted when all the browser windows are closed.\n\n\n  * Cookie\nVISITOR_PRIVACY_METADATA\n  * Duration\n6 months\n  * Description\nYouTube sets this cookie to store the user's cookie consent state for the current domain. \n\n\n  * Cookie\ncookietest\n  * Duration\nsession\n  * Description\nThe cookietest cookie is typically used to determine whether the user's browser accepts cookies, essential for website functionality and user experience.\n\n\n  * Cookie\n__Host-airtable-session\n  * Duration\n1 year\n  * Description\nThis cookie is used to enable us to integrate the services of Airtable.\n\n\n  * Cookie\n__Host-airtable-session.sig\n  * Duration\n1 year\n  * Description\nThis cookie is used to enable us to integrate the services of Airtable.\n\n\n  * Cookie\nm\n  * Duration\n1 year 1 month 4 days\n  * Description\nStripe sets this cookie for fraud prevention purposes. It identifies the device used to access the website, allowing the website to be formatted accordingly.\n\n\n  * Cookie\nBIGipServer*\n  * Duration\nsession\n  * Description\nMarketo sets this cookie to collect information about the user's online activity and build a profile about their interests to provide advertisements relevant to the user. \n\n\n  * Cookie\n__cfruid\n  * Duration\nsession\n  * Description\nCloudflare sets this cookie to identify trusted web traffic.\n\n\n  * Cookie\n_GRECAPTCHA\n  * Duration\n6 months\n  * Description\nGoogle Recaptcha service sets this cookie to identify bots to protect the website against malicious spam attacks.\n\n\n  * Cookie\n__Secure-YNID\n  * Duration\n6 months\n  * Description\nGoogle cookie used to protect user security and prevent fraud, especially during the login process.\n\n\n  * Cookie\ncookieyes-consent\n  * Duration\n1 year\n  * Description\nCookieYes sets this cookie to remember users' consent preferences so that their preferences are respected on subsequent visits to this site. It does not collect or store any personal information about the site visitors.\n\n\nFunctional\nFunctional cookies help perform certain functionalities like sharing the content of the website on social media platforms, collecting feedback, and other third-party features.\n  * Cookie\nlidc\n  * Duration\n1 day\n  * Description\nLinkedIn sets the lidc cookie to facilitate data center selection.\n\n\n  * Cookie\nbrw\n  * Duration\n1 year\n  * Description\nNo description available.\n\n\n  * Cookie\nbrwConsent\n  * Duration\n5 minutes\n  * Description\nDescription is currently not available.\n\n\n  * Cookie\nWMF-Uniq\n  * Duration\n1 year\n  * Description\nDescription is currently not available.\n\n\n  * Cookie\nloom_anon_comment\n  * Duration\n1 year\n  * Description\nNo description available.\n\n\n  * Cookie\nloom_referral_video\n  * Duration\nsession\n  * Description\nDescription is currently not available.\n\n\n  * Cookie\nVISITOR_INFO1_LIVE\n  * Duration\n6 months\n  * Description\nA cookie set by YouTube to measure bandwidth that determines whether the user gets the new or old player interface.\n\n\n  * Cookie\nyt-remote-connected-devices\n  * Duration\nNever Expires\n  * Description\nYouTube sets this cookie to store the user's video preferences using embedded YouTube videos.\n\n\n  * Cookie\nytidb::LAST_RESULT_ENTRY_KEY\n  * Duration\nNever Expires\n  * Description\nThe cookie ytidb::LAST_RESULT_ENTRY_KEY is used by YouTube to store the last search result entry that was clicked by the user. This information is used to improve the user experience by providing more relevant search results in the future.\n\n\n  * Cookie\nyt-remote-device-id\n  * Duration\nNever Expires\n  * Description\nYouTube sets this cookie to store the user's video preferences using embedded YouTube videos.\n\n\n  * Cookie\nyt-remote-session-name\n  * Duration\nsession\n  * Description\nThe yt-remote-session-name cookie is used by YouTube to store the user's video player preferences using embedded YouTube video.\n\n\n  * Cookie\nyt-remote-fast-check-period\n  * Duration\nsession\n  * Description\nThe yt-remote-fast-check-period cookie is used by YouTube to store the user's video player preferences for embedded YouTube videos.\n\n\n  * Cookie\nyt-remote-session-app\n  * Duration\nsession\n  * Description\nThe yt-remote-session-app cookie is used by YouTube to store user preferences and information about the interface of the embedded YouTube video player.\n\n\n  * Cookie\nyt-remote-cast-available\n  * Duration\nsession\n  * Description\nThe yt-remote-cast-available cookie is used to store the user's preferences regarding whether casting is available on their YouTube video player.\n\n\n  * Cookie\nyt-remote-cast-installed\n  * Duration\nsession\n  * Description\nThe yt-remote-cast-installed cookie is used to store the user's video player preferences using embedded YouTube video.\n\n\n  * Cookie\ncp_session\n  * Duration\n3 months\n  * Description\nCodepen sets this cookie for Help systems found in the website.\n\n\n  * Cookie\nloid\n  * Duration\n1 year 1 month 4 days\n  * Description\nThis cookie is set by the Reddit. The cookie enables the sharing of content from the website onto the social media platform.\n\n\nAnalytics\nAnalytical cookies are used to understand how visitors interact with the website. These cookies help provide information on metrics such as the number of visitors, bounce rate, traffic source, etc.\n  * Cookie\n__hstc\n  * Duration\n6 months\n  * Description\nHubspot set this main cookie for tracking visitors. It contains the domain, initial timestamp (first visit), last timestamp (last visit), current timestamp (this visit), and session number (increments for each subsequent session).\n\n\n  * Cookie\nhubspotutk\n  * Duration\n6 months\n  * Description\nHubSpot sets this cookie to keep track of the visitors to the website. This cookie is passed to HubSpot on form submission and used when deduplicating contacts.\n\n\n  * Cookie\n_ga\n  * Duration\n1 year 1 month 4 days\n  * Description\nGoogle Analytics sets this cookie to calculate visitor, session and campaign data and track site usage for the site's analytics report. The cookie stores information anonymously and assigns a randomly generated number to recognise unique visitors.\n\n\n  * Cookie\n_ga_*\n  * Duration\n1 year 1 month 4 days\n  * Description\nGoogle Analytics sets this cookie to store and count page views.\n\n\n  * Cookie\n__Host-psifi.analyticsTrace\n  * Duration\n6 hours\n  * Description\nDescription is currently not available.\n\n\n  * Cookie\n__Host-psifi.analyticsTraceV2\n  * Duration\n6 hours\n  * Description\nDescription is currently not available.\n\n\n  * Cookie\n_gh_sess\n  * Duration\nsession\n  * Description\nGitHub sets this cookie for temporary application and framework state between pages like what step the user is on in a multiple step form.\n\n\n  * Cookie\nYSC\n  * Duration\nsession\n  * Description\nYSC cookie is set by Youtube and is used to track the views of embedded videos on Youtube pages.\n\n\n  * Cookie\najs_anonymous_id\n  * Duration\n1 year\n  * Description\nThis cookie is set by Segment to count the number of people who visit a certain site by tracking if they have visited before.\n\n\n  * Cookie\nvuid\n  * Duration\n1 year 1 month 4 days\n  * Description\nVimeo installs this cookie to collect tracking information by setting a unique ID to embed videos on the website. \n\n\nPerformance\nPerformance cookies are used to understand and analyse the key performance indexes of the website which helps in delivering a better user experience for the visitors.\n  * Cookie\nAWSALB\n  * Duration\n7 days\n  * Description\nAWSALB is an application load balancer cookie set by Amazon Web Services to map the session to the target.\n\n\n  * Cookie\nacq\n  * Duration\npast\n  * Description\nDescription is currently not available.\n\n\n  * Cookie\nacq.sig\n  * Duration\npast\n  * Description\nDescription is currently not available.\n\n\n  * Cookie\nptc\n  * Duration\n2 years\n  * Description\nNo description available.\n\n\nAdvertisement\nAdvertisement cookies are used to provide visitors with customised advertisements based on the pages you visited previously and to analyse the effectiveness of the ad campaigns.\n  * Cookie\nmuc_ads\n  * Duration\n1 year 1 month 4 days\n  * Description\nTwitter sets this cookie to collect user behaviour and interaction data to optimize the website.\n\n\n  * Cookie\nguest_id_marketing\n  * Duration\n1 year 1 month 4 days\n  * Description\nTwitter sets this cookie to identify and track the website visitor.\n\n\n  * Cookie\nguest_id_ads\n  * Duration\n1 year 1 month 4 days\n  * Description\nTwitter sets this cookie to identify and track the website visitor.\n\n\n  * Cookie\npersonalization_id\n  * Duration\n1 year 1 month 4 days\n  * Description\nTwitter sets this cookie to integrate and share features for social media and also store information about how the user uses the website, for tracking and targeting.\n\n\n  * Cookie\nguest_id\n  * Duration\n1 year 1 month 4 days\n  * Description\nTwitter sets this cookie to identify and track the website visitor. It registers if a user is signed in to the Twitter platform and collects information about ad preferences.\n\n\n  * Cookie\nbcookie\n  * Duration\n1 year\n  * Description\nLinkedIn sets this cookie from LinkedIn share buttons and ad tags to recognize browser IDs.\n\n\n  * Cookie\n__Secure-ROLLOUT_TOKEN\n  * Duration\n6 months\n  * Description\nYouTube sets this cookie to manage feature rollout and experimentation. It helps Google control which new features or interface changes are shown to users as part of testing and staged rollouts, ensuring consistent experience for a given user during an experiment.\n\n\n  * Cookie\nyt.innertube::nextId\n  * Duration\nNever Expires\n  * Description\nYouTube sets this cookie to register a unique ID to store data on what videos from YouTube the user has seen.\n\n\n  * Cookie\nyt.innertube::requests\n  * Duration\nNever Expires\n  * Description\nYouTube sets this cookie to register a unique ID to store data on what videos from YouTube the user has seen.\n\n\n  * Cookie\nsession_tracker\n  * Duration\nsession\n  * Description\nThis cookie is set by the Reddit. This cookie is used to identify trusted web traffic. It also helps in adverstising on the website.\n\n\n  * Cookie\nedgebucket\n  * Duration\nsession\n  * Description\nReddit sets this cookie to save the information about a log-on Reddit user, for the purpose of advertisement recommendations and updating the content.\n\n\n  * Cookie\ndid\n  * Duration\n1 year\n  * Description\nArbor sets this cookie to show targeted ads to site visitors.This cookie expires after 2 months or 1 year.\n\n\nUncategorised\nOther uncategorised cookies are those that are being analysed and have not been classified into a category as yet.\nNo cookies to display.\nReject All Save My Preferences Accept All\nToggle Search[](https://towardsdatascience.com/)Toggle Mobile Navigation\n[](https://towardsdatascience.com/)\nPublish AI, ML & data-science insights to a global community of data professionals.\nSign in[Submit an Article](https://write.insightmediagroup.io)\n[Latest](https://towardsdatascience.com/latest/)[Editor's Picks](https://towardsdatascience.com/tag/editors-pick/)[Newsletter](https://towardsdatascience.com/tag/the-variable/)[ShipAI](https://towardsdatascience.com/shipai/)\n* * *\n[Write For TDS](https://towardsdatascience.com/submissions/)\n[LinkedIn](https://www.linkedin.com/company/towards-data-science/)[X](https://x.com/TDataScience)Toggle Search\n[Programming](https://towardsdatascience.com/category/programming/)\n# All You Need to Know about Writing Effective Comments in Your Code\nIt's as important as writing the source code\n[Kurtis Pykes](https://towardsdatascience.com/author/kurtispykes/)\nMay 3, 202210 min read\n![Photo by Thomas Bormans on Unsplash](https://assets.insightmediagroup.io/media/wp-content/uploads/2022/05/0iGo3G3Alg-xDDuW8-scaled.jpg)\nPhoto by [Thomas Bormans](https://unsplash.com/@thomasbormans?utm_source=medium&utm_medium=referral) on [Unsplash](https://unsplash.com?utm_source=medium&utm_medium=referral)\nComments are short, programmer-readable explanations or annotations written directly into the source code of a computer program. Although the computer ignores them while executing a program, writing effective comments in your source code may be as important as the actual code itself for the simple fact that software always remains incomplete.\nThere's always something that could be done to improve a software product or service, which means a codebase would have to be updated from time to time. It's near enough impossible to make changes or add new functionality to code that you don't understand, thus it's vital that code is always constructed such that it can be read by a human.\n> \"Programs must be written for people to read, and only incidentally for machines to execute.\"\n>   * [**Harold Abelson**](https://en.wikipedia.org/wiki/Hal_Abelson)\n> \n\nComments are employed to notify, warn, and remind others that didn't write the code [and your future self] of important things that the code is doing. In this article, we are going to be focusing on writing comments in Python.\ntext\n\n```\nTable of Contents \n- 5 Unwritten Rules about comments in Python\n    - Rule #1 Comments are complete sentences\n    - Rule #2 Comments should obey line limits\n    - Rule #3 Comments must be on the same indentation level as the code it comments\n    - Rule #4 Put a space after the #\n    - Rule #5 Links don't replace explanations\n- The different types of comments \n    - Inline comments\n    - Explanation comments\n    - Summarization comments \n    - Legal comments\n    - Code tag comments \n```\n\nLearn this step by step with the interactive [Computer Science](https://roadmap.sh/computer-science) roadmap.\n## 5 Unwritten rules about comments in Python\nWe can write single-line or multiline comments in Python. A single-line comment is defined using the `#` symbol and ends at the end of the line. Python doesn't necessarily have a dedicated syntax for multi-line comments so Pythonistas can decide between using multiple single-line comments, known wholly as block comments, or using triple quotes multi-line strings.\ntext\n\n```\n# This is a single line comment. \n```\n\ntext\n\n```\n# This is an example \n# of multiple single-line\n# comments that make up a \n# multi-line comment.\n```\n\ntext\n\n```\n\"\"\"This is an example\nof triple quotes multi-line\nstrings that make up a\nmulti-line comment.\"\"\"\n```\n\nAll three scenarios are valid, but you'll notice the triple quotes multi-line string is much more readable than using multiple single-line comments to define a multi-line comment. Thus, it's better to use triple quote multi-line strings to define a multi-line comment if it's required - remember, \"programs are written for humans to read.\"\nYou may come across people that consider comments as an afterthought or tell you \"comments aren't important,\" ignore them. Go and read any popular library's source code to see their significance. Comments are certainly required if you wish for your code to be 1) more readable and 2) more professional.\nHowever, there are 5 golden rules to follow to ensure you're writing effective code.\n### Rule #1 Comments are complete sentences\nThe entire purpose of commenting code is for it to be read by other programmers [and your future self] to gain a better understanding of what's happening in the code it's commenting. Therefore, comments should follow proper grammatical rules and include punctuation to ensure it provides clear information back to the reader.\ntext\n\n```\n# data from train dir               <-- Not good \ndata = load_data()\n```\n\ntext\n\n```\n# Load data from train directory.        <-- Good\ndata = load_data() \n```\n\n### Rule #2 Comments should obey line limits\nPython's style guide, PEP 8, was created to serve as a set of best practices for programming in Python. One of the guidelines suggests lines should be limited to 79 characters: this guide applies to source code and comments alike.\ntext\n\n```\n# This comment is so long that it doesn't even fit on one line in the code cells provided by medium.    <-- Not good \n```\n\ntext\n\n```\n# This comment is much shorter and within the limits.   <-- Good\n```\n\nProgrammers break the PEP 8 suggested line limit all the time, and that's okay - it's just a guide after all. But your comments should still obey whatever line limit you agree upon with your team [or by yourself if you're working alone].\n### Rule #3 Comments must be on the same indentation level as the code it comments\nIndentation refers to the number of spaces at the beginning of some code; Python uses four spaces as the default indentation to group code. Writing comments on different indentation levels will not cause your program to crash, but it's much easier to follow when it's on the same level.\ntext\n\n```\ndef example_function(): \n# Perform a random calculation.        <-- Not good\n    random = 24 + 4\n    return random\n```\n\ntext\n\n```\ndef example_function(): \n    # Perform a random calculation.        <-- Good\n    random = 24 + 4\n    return random\n```\n\n### Rule #4 Put a space after the\nPutting a space after `#` helps with readability.\ntext\n\n```\n#This is valid but not easy to read.        <-- Not good\n# This is valid and easy to read.           <-- Good\n```\n\n### Rule #5 Links don't replace explanations\nSometimes we may need to link to external pages to further explain what our code is doing. Merely leaving a link to the page is not as effective as writing why the code is being implemented before linking to the external resource. The reason for this is that pages can be taken down, then you'll be left with an unexplained link that navigates to nowhere.\n**Note** : _The example code below is a snippet from the [Scikit-learn codebase](https://github.com/scikit-learn/scikit-learn/blob/main/sklearn/model_selection/_search_successive_halving.py)._\ntext\n\n```\n# Not good\ndef _check_input_parameters(self, X, y, groups): \n\n    --- snip ---\n    # see https://github.com/scikit-learn/scikit-learn/issues/15149\n    if not _yields_constant_splits(self._checked_cv_orig): \n        raise ValueError(\n            \"The cv parameter must yield consistent folds across \"\n            \"calls to split(). Set its random_state to an int, or \"\n            \" set shuffle=False.\"\n        )\n    --- snip ---\n```\n\ntext\n\n```\n# Good\ndef _check_input_parameters(self, X, y, groups): \n\n    --- snip --- \n```\n\ntext\n\n```\n    # We need to enforce that successive calls to cv.split() yield \n    # the same splits: \n    # see https://github.com/scikit-learn/scikit-learn/issues/15149\n```\n\ntext\n\n```\n    if not _yields_constant_splits(self._checked_cv_orig): \n        raise ValueError(\n            \"The cv parameter must yield consistent folds across \"\n            \"calls to split(). Set its random_state to an int, or \"\n            \" set shuffle=False.\"\n        )\n    --- snip --- \n```\n\n_**Note**_ _: The good example could have been made better by using triple-quote multiline strings but the convention in the Scikit-learn codebase is to use multiple single-line comments hence why it's been followed._\nOne of the first arguments you'll hear from developers who aren't as keen on following rules is \"you're overthinking it.\" To some degree, they have a point: your program will not crash if you decide to go against every rule presented above.\nHowever, a major part of programming is collaboration. As much as you strive to be a great programmer that builds phenomenal things, you should also remember that a large portion of your work will be done as part of a team [in most cases]. Thus, it helps to consider how you can make your code easier for others to understand and one aspect of this is how you write your comments.\nThe more readable your comments are, the more likely other developers [and your future self] are to read them: your comments are only beneficial if they're being read. Part of ensuring your comments are read is knowing how to place them effectively.\n## The different types of comments\nComments serve as an extra form of documentation for your source code. Thus, the general purpose of them is to inform others [including your future self] of why some functionality in the code is implemented in a certain manner, but there are several different ways to deploy comments to achieve this goal.\nLet's take a look at a few of these methods:\n### Inline comments\nInline comments come at the end of a line of code. There are two main reasons to use an inline comment:\n**#1** If a variable has been defined but the reason for using a specific object is unclear, you can use an inline comment to justify your decision.\ntext\n\n```\nAGE = 18 # The legal drinking age in the UK. \n```\n\n**#2** Another good use of an inline comment is to reduce ambiguity by providing more context to what's being defined.\ntext\n\n```\nday = 3 # Days in a week range from 0 (Mon) to 6 (Sun)\nheight = 1.75 # Height is given in meters \n```\n\nYou may also see some codebases that use comments to specify a variable's data type.\ntext\n\n```\n\"\"\"Code taken from my fraud detection model project.\nSee: https://github.com/kurtispykes/fraud-detection-project/blob/main/IEEE-CIS%20Fraud%20Detection/packages/fraud_detection_model/fraud_detection_model/train_pipeline.py\"\"\"\n```\n\ntext\n\n```\nfrom config.core import config  # type: ignore\nfrom pipeline import fraud_detection_pipe  # type: ignore\nfrom processing.data_manager import load_datasets, save_pipeline  # type: ignore\nfrom sklearn.model_selection import train_test_split  # type: ignore\n```\n\nThe only reason I did this in my project was that I was using an automated tool called [typechecks](https://pypi.org/project/typechecks/) to validate data types - I assume that's the reason it may occur in other codebases too.\nMore often than not, you don't need to specify the data type because it's obvious from the assignment statement.\n### Explanation comments\nThe main goal of a comment is to explain why a specific piece has been implemented in a certain manner. As you'd know, there are several ways to do things so an explanation gives more insight into the programmer's intentions.\nFor example, take a look at this comment:\ntext\n\n```\nnumber_of_words *= 0.2 # Multiply the number of words by 0.2. \n```\n\nThe above scenario is a perfect example of a pointless comment. It doesn't take a rocket scientist to figure out that you're multiplying the `number_of_words` by `0.2` so it's not necessary to state it again in a comment.\nHere's an improved version:\ntext\n\n```\nnumber_of_words *= 0.2 # Account for each word valued at $0.20.  \n```\n\nThis comment provides more insight into the intent of the programmer: we now know that `0.2` is the price per word.\n**Note** : _If you've read [**7 Code Smells You Should Know About and Avoid**](https://towardsdatascience.com/7-code-smells-you-should-know-about-and-avoid-b1edf066c3a5), you'd know that we could have improved this code more by omitting the magic number by assigning it a constant (i.e., `PRICE_PER_WORD = 0.2`)._\n### Summarization comments\nSometimes we have no choice but to use several lines of code to implement some functionality. Helping your colleagues [and your future self] by giving them a summary of what your code is doing is extremely beneficial as it permits them to quickly skim through your code.\ntext\n\n```\n\"\"\"This is a small piece of functionality extracted from \nthe Scikit-learn codebase. See: https://github.com/scikit-learn/scikit-learn/blob/main/sklearn/impute/_knn.py#L262\"\"\"\n```\n\ntext\n\n```\n# Removes columns where the training data is all nan\nif not np.any(mask):\n    return X[:, valid_mask]\n```\n\ntext\n\n```\nrow_missing_idx = np.flatnonzero(mask.any(axis=1))\n```\n\ntext\n\n```\nnon_missing_fix_X = np.logical_not(mask_fit_X)\n```\n\ntext\n\n```\n# Maps from indices from X to indices in dist matrix\ndist_idx_map = np.zeros(X.shape[0], dtype=int)        dist_idx_map[row_missing_idx] = np.arange(row_missing_idx.shape[0])\n```\n\nSummary comments are simply a high-level overview of what is going on in the code. Dotting them in various places in your codebase makes it extremely easy for teammates [and your future self] to quickly skim through code for a better understanding - it also shows you know how the code works.\n### Legal comments\nDepending on where you work, you may have to include copyright, software licensing, and authorship information at the top of your scripts - it's more of an internal policy than a necessity for all programmers.\nHere's an example from Scikit-learn's `[_knn.py](https://github.com/scikit-learn/scikit-learn/blob/main/sklearn/impute/_knn.py#L262)` source file:\ntext\n\n```\n# Authors: Ashim Bhattarai <ashimb9@gmail.com>\n#          Thomas J Fan <thomasjpfan@gmail.com>\n# License: BSD 3 clause\n```\n\n### Code tag comments\nIt's not unusual to find short reminder comments scattered around various source files. Developers do this to remind themselves about things they haven't gotten round to just yet but intend to in the future.\nThe most common tag you'll find is the TODO tag.\ntext\n\n```\n\"\"\"This is an example of a code tag comment in the\nScikit-learn codebase. The full code can be found here:\nhttps://github.com/scikit-learn/scikit-learn/blob/main/sklearn/metrics/pairwise.py\"\"\"\n```\n\ntext\n\n```\ndef pairwise_distances_argmin_min(\nX, Y, *, axis=1, metric=\"euclidean\", metric_kwargs=None\n):\n    --- snip ---\n    else:\n        # TODO: once PairwiseDistancesArgKmin supports sparse input \n        # matrices and 32 bit, we won't need to fallback to \n        # pairwise_distances_chunked anymore. Turn off check for \n        # finiteness because this is costly and because array\n        # shave already been validated.\n    --- snip ---\n```\n\nNotice how the example above provides a clear description of what's to be done - this is imperative if you're using code tags.\nThese comments shouldn't be used as a replacement for some formal tracker or bug report tools since it's extremely easy to forget they exist if you're not reading the section they're in.\nIt's important to note that all of these conventions aren't strictly enforced by Python. Teams may have their own conventions about commenting code and in those situations, it's better to follow the provided structure. But always remember that your code is going to be read so making it as readable as possible is going to make that process easier for whoever that person may be.\nAre there any types of comments I've missed? Leave a comment.\n_Thanks for reading._\n**Connect with me:** [LinkedIn](https://www.linkedin.com/in/kurtispykes/) [Twitter](https://twitter.com/KurtisPykes) [Instagram](https://www.instagram.com/kurtispykes/)\nIf you enjoy reading stories like this one and wish to support my writing, consider [becoming a Medium member](https://kurtispykes.medium.com/membership). With a $5 a month commitment, you unlock unlimited access to stories on Medium. If you use [my sign-up link](https://kurtispykes.medium.com/membership), I'll receive a small commission.\nAlready a member? [Subscribe](https://kurtispykes.medium.com/subscribe) to be notified when I publish.\n> [**Get an email whenever Kurtis Pykes publishes.**](https://kurtispykes.medium.com/subscribe)\n## Register Now to Continue Reading\n### Unlock Towards Data Science with a Free Account\nAll articles on Towards Data Science are available to registered users. Create a free account today to access this article and thousands more.\nRegister for freeSign in to your account\n* * *\n![](https://assets.insightmediagroup.io/media/1787657084566_vncpf1.jpeg)\nWritten By\n## [Kurtis Pykes](https://towardsdatascience.com/author/kurtispykes/)\n[See all from Kurtis Pykes](https://towardsdatascience.com/author/kurtispykes/)\n[Code Comments](https://towardsdatascience.com/tag/code-comments/)[Programming](https://towardsdatascience.com/tag/programming/)[Python](https://towardsdatascience.com/tag/python/)[Software Development](https://towardsdatascience.com/tag/software-development/)[Technology](https://towardsdatascience.com/tag/technology/)\nShare This Article\n  * [](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Ftowardsdatascience.com%2Fall-you-need-to-know-about-writing-effective-comments-in-your-code-41134a5acb60%2F&title=All%20You%20Need%20to%20Know%20about%20Writing%20Effective%20Comments%20in%20Your%20Code)\n  * [](https://www.linkedin.com/shareArticle?mini=true&url=https%3A%2F%2Ftowardsdatascience.com%2Fall-you-need-to-know-about-writing-effective-comments-in-your-code-41134a5acb60%2F&title=All%20You%20Need%20to%20Know%20about%20Writing%20Effective%20Comments%20in%20Your%20Code)\n  * [](https://x.com/share?url=https%3A%2F%2Ftowardsdatascience.com%2Fall-you-need-to-know-about-writing-effective-comments-in-your-code-41134a5acb60%2F&text=All%20You%20Need%20to%20Know%20about%20Writing%20Effective%20Comments%20in%20Your%20Code)\n\n\nTowards Data Science is a community publication. Submit your insights to reach our global audience and earn through the TDS Author Payment Program.\n[Write for TDS](https://towardsdatascience.com/submissions/)\n## Related Articles\n  * [![](https://assets.insightmediagroup.io/media/wp-content/uploads/2021/05/07IsYbQH_s7o3NQxI-scaled.jpg)](https://towardsdatascience.com/7-great-youtube-channels-to-learn-the-latest-advancements-in-machine-learning-and-ai-f3a9b5f56b65/)\n## [8 Great Youtube Channels to Learn the Latest Advancements in Machine Learning and AI](https://towardsdatascience.com/7-great-youtube-channels-to-learn-the-latest-advancements-in-machine-learning-and-ai-f3a9b5f56b65/)\n[Artificial Intelligence](https://towardsdatascience.com/category/artificial-intelligence/)\nIf you have a hard time understanding Machine Learning papers, here are 8 YouTube channels that can help you out\n[Fatos Morina](https://towardsdatascience.com/author/fatosmorina/)\nMay 24, 20216 min read\n  * [![](https://assets.insightmediagroup.io/media/wp-content/uploads/2019/11/0GZnOSup47cj8Vlzk-scaled.jpg)](https://towardsdatascience.com/time-series-analysis-from-scratch-in-python-part-2-1408e91e5e02/)\n## [Time Series Analysis From Scratch in Python: Part 2](https://towardsdatascience.com/time-series-analysis-from-scratch-in-python-part-2-1408e91e5e02/)\n[Artificial Intelligence](https://towardsdatascience.com/category/artificial-intelligence/)\nLearn about Time Resampling and Time Shifting\n[Dario Radečić](https://towardsdatascience.com/author/radecicdario/)\nNovember 19, 20194 min read\n  * [![](https://assets.insightmediagroup.io/media/wp-content/uploads/2020/09/1QhQoPLFgI3tMrc7cwBzgkQ-scaled.jpeg)](https://towardsdatascience.com/what-does-doesnt-follow-benford-s-law-7d0b3c14afa5/)\n## [What does/doesn't follow Benford's law](https://towardsdatascience.com/what-does-doesnt-follow-benford-s-law-7d0b3c14afa5/)\n[Data Science](https://towardsdatascience.com/category/data-science/)\nAn analysis of hundreds of sets of numbers from Wikidata.\n[Mathieu d'Aquin](https://towardsdatascience.com/author/mathieu.daquin.x/)\nSeptember 27, 202013 min read\n  * [![](https://assets.insightmediagroup.io/media/wp-content/uploads/2024/02/1iUGjk-QBLCHh_cakb5Z1bw.png)](https://towardsdatascience.com/nine-rules-for-accessing-cloud-files-from-your-rust-code-d456c1e2ceb4/)\n## [Nine Rules for Accessing Cloud Files from Your Rust Code](https://towardsdatascience.com/nine-rules-for-accessing-cloud-files-from-your-rust-code-d456c1e2ceb4/)\n[](https://towardsdatascience.com/all-you-need-to-know-about-writing-effective-comments-in-your-code-41134a5acb60/)\nPractical Lessons from Upgrading Bed-Reader, a Bioinformatics Library\n[Carl Kadie](https://towardsdatascience.com/author/carlmkadie/)\nFebruary 7, 202423 min read\n  * [![](https://assets.insightmediagroup.io/media/wp-content/uploads/2021/12/18pPrgUYTar9NZ69sm3HfSg-scaled.jpeg)](https://towardsdatascience.com/i-took-12-data-science-courses-for-3-months-heres-what-i-wish-i-knew-earlier-67acc6baa73/)\n## [I Took 12 Data Science Courses For 3 Months - Here's What I Wish I Knew Earlier](https://towardsdatascience.com/i-took-12-data-science-courses-for-3-months-heres-what-i-wish-i-knew-earlier-67acc6baa73/)\n[Programming](https://towardsdatascience.com/category/programming/)\nThe pros and cons of successfully taking a data science course.\n[Benjamin Nweke](https://towardsdatascience.com/author/benjaminnweke/)\nDecember 14, 20217 min read\n  * [![](https://assets.insightmediagroup.io/media/wp-content/uploads/2019/11/1asIJTTrG236Dkii_0xmQiQ-scaled.jpeg)](https://towardsdatascience.com/when-not-to-use-machine-learning-14ec62daacd7/)\n## [When not to use machine learning?](https://towardsdatascience.com/when-not-to-use-machine-learning-14ec62daacd7/)\n[Artificial Intelligence](https://towardsdatascience.com/category/artificial-intelligence/)\nMachine learning models, rules or heuristic approaches?\n[Low Wei Hong](https://towardsdatascience.com/author/lowweihong/)\nNovember 17, 20195 min read\n  * [![](https://assets.insightmediagroup.io/media/wp-content/uploads/2023/11/0qOU4gWJ3G0_RSpyG-scaled.jpg)](https://towardsdatascience.com/the-new-best-python-package-for-visualising-network-graphs-e220d59e054e/)\n## [The New Best Python Package for Visualising Network Graphs](https://towardsdatascience.com/the-new-best-python-package-for-visualising-network-graphs-e220d59e054e/)\n[Data Science](https://towardsdatascience.com/category/data-science/)\nA guide on who should use it, when to use it, how to use it, and why I was wrong before...\n[Benjamin Lee](https://towardsdatascience.com/author/bl3e967/)\nNovember 23, 202310 min read\n  * [![](https://assets.insightmediagroup.io/media/wp-content/uploads/2023/01/17DvMprK27y_KSW4c-m3OUw.png)](https://towardsdatascience.com/how-to-securely-connect-synapse-pipelines-to-azure-functions-9bcdb176e150/)\n## [How to Securely Connect Synapse Pipelines to Azure Functions](https://towardsdatascience.com/how-to-securely-connect-synapse-pipelines-to-azure-functions-9bcdb176e150/)\n[Programming](https://towardsdatascience.com/category/programming/)\nLearn to use Synapse exfiltration protection, private endpoints and Azure AD authentication to consume Functions\n[René Bremer](https://towardsdatascience.com/author/rebremer/)\nJanuary 4, 20234 min read\n  * [![](https://assets.insightmediagroup.io/media/wp-content/uploads/2022/07/0f04RDocsnYpmz6gx-scaled.jpg)](https://towardsdatascience.com/views-an-underrated-alternative-to-tables-in-sql-26cd6d1d8660/)\n## [Views: An Underrated Alternative to Tables in SQL](https://towardsdatascience.com/views-an-underrated-alternative-to-tables-in-sql-26cd6d1d8660/)\n[Programming](https://towardsdatascience.com/category/programming/)\nSQL users will benefit greatly from developing the habit of using views early on\n[Aashish Nair](https://towardsdatascience.com/author/aashishnair/)\nJuly 26, 20224 min read\n\n\n  * [YouTube](https://www.youtube.com/c/TowardsDataScience)\n  * [X](https://x.com/TDataScience)\n  * [LinkedIn](https://www.linkedin.com/company/towards-data-science/)\n  * [Threads](https://www.threads.net/@towardsdatascience)\n  * [Bluesky](https://bsky.app/profile/towardsdatascience.com)\n\n\n[](https://towardsdatascience.com/)\nYour home for data science and AI. The world's leading publication for data science, data analytics, data engineering, machine learning, and artificial intelligence professionals.\nSubscribe to Our Newsletter[Write For TDS](https://towardsdatascience.com/submissions/)•[About](https://towardsdatascience.com/about-towards-data-science-d691af11cc2f/)•[Advertise](https://contact.towardsdatascience.com/advertise-with-towards-data-science)•[Privacy Policy](https://towardsdatascience.com/privacy-policy/)•[Terms of Use](https://towardsdatascience.com/website-terms-of-use/)\n© Insight Media Group, LLC 2026•[The New Stack](https://thenewstack.io)•[roadmap.sh](https://roadmap.sh)•[Creator Network](https://insightmediagroup.io/creator-network)\n####  Recommended Articles \nClose\n  * [ ![](https://h030.towardsdatascience.com/rest/v2/contentStores/d7d3a4ab-7caf-4383-bbd2-fbf7fb4f1787/items/607631/image?etag=1781543525510&width=500&height=500) Critical Mistakes Companies Make When Integrating AI/ML into Their Processes ](https://towardsdatascience.com/critical-mistakes-companies-make-when-integrating-ai-ml-into-their-processes/ \"Critical Mistakes Companies Make When Integrating AI/ML into Their Processes\")\n  * [ ![](https://h030.towardsdatascience.com/rest/v2/contentStores/d7d3a4ab-7caf-4383-bbd2-fbf7fb4f1787/items/607686/image?etag=1782161464448&width=500&height=500) How Relevance Models Foreshadowed Transformers for NLP ](https://towardsdatascience.com/how-relevance-models-foreshadowed-transformers-for-nlp/ \"How Relevance Models Foreshadowed Transformers for NLP\")\n  * [ ![](https://h030.towardsdatascience.com/rest/v2/contentStores/d7d3a4ab-7caf-4383-bbd2-fbf7fb4f1787/items/607639/image?etag=1781250125848&width=500&height=500) Javascript Fatigue: HTMX Is All You Need to Build ChatGPT — Part 1 ](https://towardsdatascience.com/javascript-fatigue-you-dont-need-js-to-build-chatgpt/ \"Javascript Fatigue: HTMX Is All You Need to Build ChatGPT — Part 1\")\n  * [ ![](https://h030.towardsdatascience.com/rest/v2/contentStores/d7d3a4ab-7caf-4383-bbd2-fbf7fb4f1787/items/607930/image?etag=1782124566054&width=500&height=500) The Subset Sum Problem Solved in Linear Time for Dense Enough Inputs ](https://towardsdatascience.com/subset-sum-problem-solved-in-linear-time-for-dense-enough-inputs/ \"The Subset Sum Problem Solved in Linear Time for Dense Enough Inputs\")\n\n\n",
  "metadata": {
    "title": "All You Need to Know about Writing Effective Comments in Your Code | Towards Data Science",
    "description": "It's as important as writing the source code",
    "keywords": null,
    "author": "Kurtis Pykes",
    "og:locale": "en_US",
    "og:type": "article",
    "og:title": "All You Need to Know about Writing Effective Comments in Your Code",
    "og:description": "It's as important as writing the source code",
    "og:url": "https://towardsdatascience.com/all-you-need-to-know-about-writing-effective-comments-in-your-code-41134a5acb60/",
    "og:site_name": "Towards Data Science",
    "og:image": "https://assets.insightmediagroup.io/media/wp-content/uploads/2022/05/0iGo3G3Alg-xDDuW8-scaled.jpg",
    "og:image:width": "2560",
    "og:image:height": "1707",
    "og:image:type": "image/jpeg",
    "twitter:card": "summary_large_image",
    "twitter:site": "@TDataScience",
    "twitter:creator": "@TDataScience",
    "twitter:label1": "Written by",
    "twitter:data1": "Kurtis Pykes",
    "twitter:label2": "Est. reading time",
    "twitter:data2": "10 min read",
    "article:published_time": "2022-05-03T19:27:45.000Z",
    "article:modified_time": "2022-05-03T19:27:45.000Z",
    "article:author": "https://towardsdatascience.com/author/kurtispykes/"
  },
  "paywall": {
    "listed_paid": true,
    "detected": false,
    "marker": "",
    "public_only": true,
    "policy": "付费/会员内容只保留页面公开可见部分，不绕过付费墙"
  },
  "crawl": {
    "success": true,
    "status_code": 200,
    "error": ""
  },
  "code_blocks": [
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_000.txt",
      "chars": 487
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_001.txt",
      "chars": 34
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_002.txt",
      "chars": 97
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_003.txt",
      "chars": 96
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_004.txt",
      "chars": 69
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_005.txt",
      "chars": 70
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_006.txt",
      "chars": 118
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_007.txt",
      "chars": 65
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_008.txt",
      "chars": 115
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_009.txt",
      "chars": 115
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_010.txt",
      "chars": 110
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_011.txt",
      "chars": 429
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_012.txt",
      "chars": 76
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_013.txt",
      "chars": 160
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_014.txt",
      "chars": 283
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_015.txt",
      "chars": 46
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_016.txt",
      "chars": 98
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_017.txt",
      "chars": 226
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_018.txt",
      "chars": 255
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_019.txt",
      "chars": 63
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_020.txt",
      "chars": 66
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_021.txt",
      "chars": 176
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_022.txt",
      "chars": 102
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_023.txt",
      "chars": 51
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_024.txt",
      "chars": 47
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_025.txt",
      "chars": 175
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_026.txt",
      "chars": 119
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_027.txt",
      "chars": 193
    },
    {
      "language": "txt",
      "file": "attachments/f8be502f0a93/code/block_028.txt",
      "chars": 436
    }
  ],
  "images": [
    {
      "src": "https://assets.insightmediagroup.io/media/wp-content/uploads/2022/05/0iGo3G3Alg-xDDuW8-scaled.jpg",
      "alt": "Photo by Thomas Bormans on Unsplash",
      "local_path": "attachments/f8be502f0a93/images/000.jpg",
      "bytes": 327018,
      "downloaded": true
    },
    {
      "src": "https://assets.insightmediagroup.io/media/wp-content/uploads/2021/05/07IsYbQH_s7o3NQxI-scaled.jpg",
      "alt": "",
      "local_path": "attachments/f8be502f0a93/images/001.jpg",
      "bytes": 269566,
      "downloaded": true
    },
    {
      "src": "https://assets.insightmediagroup.io/media/wp-content/uploads/2019/11/0GZnOSup47cj8Vlzk-scaled.jpg",
      "alt": "",
      "local_path": "attachments/f8be502f0a93/images/002.jpg",
      "bytes": 173979,
      "downloaded": true
    },
    {
      "src": "https://assets.insightmediagroup.io/media/wp-content/uploads/2020/09/1QhQoPLFgI3tMrc7cwBzgkQ-scaled.jpeg",
      "alt": "",
      "local_path": "attachments/f8be502f0a93/images/003.jpeg",
      "bytes": 870956,
      "downloaded": true
    },
    {
      "src": "https://assets.insightmediagroup.io/media/wp-content/uploads/2024/02/1iUGjk-QBLCHh_cakb5Z1bw.png",
      "alt": "",
      "local_path": "attachments/f8be502f0a93/images/004.png",
      "bytes": 1590088,
      "downloaded": true
    },
    {
      "src": "https://assets.insightmediagroup.io/media/wp-content/uploads/2021/12/18pPrgUYTar9NZ69sm3HfSg-scaled.jpeg",
      "alt": "",
      "local_path": "attachments/f8be502f0a93/images/005.jpeg",
      "bytes": 310790,
      "downloaded": true
    },
    {
      "src": "https://assets.insightmediagroup.io/media/wp-content/uploads/2019/11/1asIJTTrG236Dkii_0xmQiQ-scaled.jpeg",
      "alt": "",
      "local_path": "attachments/f8be502f0a93/images/006.jpeg",
      "bytes": 545101,
      "downloaded": true
    },
    {
      "src": "https://assets.insightmediagroup.io/media/wp-content/uploads/2023/11/0qOU4gWJ3G0_RSpyG-scaled.jpg",
      "alt": "",
      "local_path": "attachments/f8be502f0a93/images/007.jpg",
      "bytes": 528609,
      "downloaded": true
    },
    {
      "src": "https://assets.insightmediagroup.io/media/wp-content/uploads/2023/01/17DvMprK27y_KSW4c-m3OUw.png",
      "alt": "",
      "local_path": "attachments/f8be502f0a93/images/008.png",
      "bytes": 1541701,
      "downloaded": true
    },
    {
      "src": "https://assets.insightmediagroup.io/media/wp-content/uploads/2022/07/0f04RDocsnYpmz6gx-scaled.jpg",
      "alt": "",
      "local_path": "attachments/f8be502f0a93/images/009.jpg",
      "bytes": 269760,
      "downloaded": true
    }
  ],
  "audio": [],
  "videos": [
    {
      "src": "https://www.youtube.com/c/TowardsDataScience",
      "quality": "unavailable",
      "local_path": "",
      "note": "无1080p且无720p，未交付更低清晰度"
    }
  ],
  "links": [
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/latest/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/tag/editors-pick/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/tag/the-variable/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/shipai/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/submissions/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/category/programming/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/author/kurtispykes/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/7-code-smells-you-should-know-about-and-avoid-b1edf066c3a5"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/tag/code-comments/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/tag/programming/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/tag/python/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/tag/software-development/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/tag/technology/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/7-great-youtube-channels-to-learn-the-latest-advancements-in-machine-learning-and-ai-f3a9b5f56b65/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/category/artificial-intelligence/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/author/fatosmorina/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/time-series-analysis-from-scratch-in-python-part-2-1408e91e5e02/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/author/radecicdario/"
    },
    {
      "type": "internal",
      "href": "https://towardsdatascience.com/what-does-doesnt-follow-benford-s-law-7d0b3c14afa5/"
    },
    {
      "type": "external",
      "href": "https://write.insightmediagroup.io"
    },
    {
      "type": "external",
      "href": "https://www.linkedin.com/company/towards-data-science/"
    },
    {
      "type": "external",
      "href": "https://x.com/TDataScience"
    },
    {
      "type": "external",
      "href": "https://unsplash.com/@thomasbormans"
    },
    {
      "type": "external",
      "href": "https://unsplash.com"
    },
    {
      "type": "external",
      "href": "https://en.wikipedia.org/wiki/Hal_Abelson"
    },
    {
      "type": "external",
      "href": "https://roadmap.sh/computer-science"
    },
    {
      "type": "external",
      "href": "https://github.com/scikit-learn/scikit-learn/blob/main/sklearn/model_selection/_search_successive_halving.py"
    },
    {
      "type": "external",
      "href": "https://pypi.org/project/typechecks/"
    },
    {
      "type": "external",
      "href": "https://www.linkedin.com/in/kurtispykes/"
    },
    {
      "type": "external",
      "href": "https://twitter.com/KurtisPykes"
    },
    {
      "type": "external",
      "href": "https://www.instagram.com/kurtispykes/"
    },
    {
      "type": "external",
      "href": "https://kurtispykes.medium.com/membership"
    },
    {
      "type": "external",
      "href": "https://kurtispykes.medium.com/subscribe"
    },
    {
      "type": "external",
      "href": "https://www.facebook.com/sharer/sharer.php?title=All+You+Need+to+Know+about+Writing+Effective+Comments+in+Your+Code&u=https%3A%2F%2Ftowardsdatascience.com%2Fall-you-need-to-know-about-writing-effective-comments-in-your-code-41134a5acb60%2F"
    },
    {
      "type": "external",
      "href": "https://www.linkedin.com/shareArticle?mini=true&title=All+You+Need+to+Know+about+Writing+Effective+Comments+in+Your+Code&url=https%3A%2F%2Ftowardsdatascience.com%2Fall-you-need-to-know-about-writing-effective-comments-in-your-code-41134a5acb60%2F"
    },
    {
      "type": "external",
      "href": "https://x.com/share?text=All+You+Need+to+Know+about+Writing+Effective+Comments+in+Your+Code&url=https%3A%2F%2Ftowardsdatascience.com%2Fall-you-need-to-know-about-writing-effective-comments-in-your-code-41134a5acb60%2F"
    },
    {
      "type": "external",
      "href": "https://www.youtube.com/c/TowardsDataScience"
    },
    {
      "type": "external",
      "href": "https://www.threads.net/@towardsdatascience"
    },
    {
      "type": "external",
      "href": "https://bsky.app/profile/towardsdatascience.com"
    }
  ],
  "repair_version": 2,
  "repaired_at": "2026-10-14T11:11:49Z",
  "source_url": "https://towardsdatascience.com/all-you-need-to-know-about-writing-effective-comments-in-your-code-41134a5acb60/",
  "delivery_status": "excluded_paid",
  "discovery_status": "excluded_paid",
  "missing_reason": "按原约定排除付费/会员全文"
}