{"id":12055,"date":"2022-04-19T17:51:49","date_gmt":"2022-04-19T17:51:49","guid":{"rendered":"https:\/\/www.directimpactsolutions.com\/?p=12055"},"modified":"2023-05-22T19:25:58","modified_gmt":"2023-05-22T19:25:58","slug":"good-comments-vs-bad-comments","status":"publish","type":"post","link":"https:\/\/www.directimpactsolutions.com\/en\/good-comments-vs-bad-comments\/","title":{"rendered":"Code Readability: Good Comments vs. Bad Comments"},"content":{"rendered":"
\"good<\/figure>

This article will show examples of good comments vs. bad comments, and how you can improve your code readability by following a few key principles. In our previous blog posts on code readability, we showed how to enhance code readability by\u00a0using spacing\u00a0and\u00a0meaningful naming<\/a>\u00a0without adding comments.<\/p>

Some of you might be wondering, what\u2019s wrong with comments?<\/p>

Accurate, well-placed, informative, and intention-revealing comments are good; however, most comments are not this way.<\/p>

Why are most comments bad?<\/h3>

Most comments are bad because developers can\u2019t realistically maintain them. Over time, comments can become inaccurate and misleading, which is worse than not having comments.<\/p>

Not all comments need to be there. Often, we write a bunch of script steps that we know are confusing and disorganized, so we add comments to make our script more readable.<\/p>

How does this affect our code?<\/h3>

What we are doing is creating two narratives for our scripts; one lives in the script steps, and one lives in the comments. If the narrative that lives in the script steps is unclear and not expressive, we attempt to compensate for it by creating another one.<\/p>

Between the two narratives, only one of them contains the truth, which is the one that will be executed by your solution, your script steps. As time goes on, the narrative captured by comments might become inaccurate, and eventually, become lies.<\/p>

Let\u2019s look at some examples of good comments vs. bad comments.<\/p>

Types of Bad Comments<\/h3>

Redundant Comments<\/strong><\/h4>
\"\"<\/figure>

Look at the comment above that says New Window right before an actual New Window script step. It\u2019s obviously redundant.<\/p>

\"\"<\/figure>

But what about this \u201cFind the project\u201d comment in front of four script steps performing a find? It must be providing some value by using one row to tell you what the next four rows are doing, right? Not really. This comment is not more informative than the script steps themselves, so there\u2019s no need to add it.<\/p>

Comments that aren\u2019t intention-revealing<\/strong><\/h4>
\"\"<\/figure>

Let\u2019s look at this comment that says, \u201cProject ID must be added to the script parameter when creating a new project.\u201d The meaning of this comment might be clear in the head of the developer who wrote this, but it\u2019s not obvious to others. This comment seems to be telling some rules, but it doesn\u2019t explain the reason behind the rule or what purpose this rule serves.<\/p>

This step makes sure that when it is called a second time in the same workflow, the new project created the first time will be found so that the user can resume editing. So we should say something along that line, like \u201cMake sure the project created can be found when the script is called again.\u201c<\/p>

Misleading comments<\/strong><\/h4>
\"\"<\/figure>

Misleading comment<\/p>

This comment above is misleading, the script opens up a new window and navigates the user to a layout based on the project context. However, when the script ends, it closes the new window. So it doesn\u2019t guarantee to put the user in any specific context.<\/p>

Other developers will see this comment and assume that when the script finishes, they will be in the project context. They might write some additional features to run after this script that depends on the project context, and then they will be sorry.<\/p>

In this case, instead of removing the comment, I\u2019ll correct it, because context is very important in FileMaker. Announcing your start and end context makes it much easier to interface your script with others\u2019 development work.<\/p>

\"\"<\/figure>

Corrected comment<\/p>

Commented-out script steps<\/strong><\/h4>
\"\"<\/figure>

Yes, we\u2019ve all created this at some point. Commented-out script steps make people wonder why they are commented out. Are they important? Were they left there as a reminder for something? How long have they been there?<\/p>

If you are scared of deleting commented code because you don\u2019t want to lose work, save a copy of your file or create a DDR; there\u2019s no need to hoard these comments in your solution.<\/p>

Comments containing nonlocal information<\/strong><\/h4>
\"\"<\/figure>

Check out the line that says if the employee to assign doesn\u2019t exist, the user can create the employee and then assign it to the project. It is saying something informative, but why is it here? It should probably be moved up, right below the \u201cElse If [$userAction = \u201cAdd Assignee\u201d] line to explain what this entire branch is doing. Or, perhaps it should be removed as the branching condition itself is quite informative.<\/p>

Comments should describe adjacent script steps. Don\u2019t offer system-wide or out-of-context information using comments.<\/p>

Comments containing too much information<\/strong><\/h4>
\"\"<\/figure>

When I said a good script should read like a well-written article, I don\u2019t want to encourage developers to actually write articles in their script using comments. Overall, if you can use meaningful naming and spacing to express something, don\u2019t use comments, and don\u2019t comment on bad code. Just rewrite it.<\/p>

OK, enough with bad comments. Let\u2019s look at some good ones.<\/p>

Types of Good Comments<\/h3>

Informative comments<\/strong><\/h4>
\"\"<\/figure>

This header comment summarizes 14 lines of content<\/p>

I like to use these comments in front of a block of script steps. I call them block headers. They are supposed to summarize what a large block of code is intended to do, which helps the reader comprehend the script\u2019s workflow and locate the script steps they are looking for.<\/p>

Explanation of intent<\/strong><\/h4>
\"\"<\/figure>

After rewriting one of our bad comments, it now reveals the intention of the writer. It\u2019s a good comment now.<\/p>

Warning of consequences<\/strong><\/h4>
\"\"<\/figure>

Sometimes it is useful to warn others about certain consequences. But do be mindful about using comments this way. If you find yourself having to constantly write warning comments, perhaps consider rearchitecting your code so it\u2019s less dangerous.<\/p>

Journal comments<\/strong><\/h4>
\"\"<\/figure>

If this was any other technology that can leverage modern version control software to manage changes, journal comments will be completely redundant. But since FileMaker can\u2019t do that, I\u2019ll leave it here as good ones.<\/p>

Final Result<\/h3>

By adding meaningful comments, our script is now much cleaner than the script we started with. These comments, strategic spacing, and naming conventions have improved our code readability. We hope that this analysis of good vs. bad comments is useful for your development skills.<\/p>

If you prefer to learn in video format, check out our video<\/a> on Good Comments vs. Bad Comments.<\/p>

*This article was originally written for AppWorks, which has since joined Direct Impact Solutions. This article is intended for informative purposes only. To the best of our knowledge, this information is accurate as of the date of publication.<\/em><\/p>","protected":false},"excerpt":{"rendered":"

This article will show examples of good comments vs. bad comments, and how you can improve your code readability by following a few key principles. In our previous blog posts on code readability, we showed how to enhance code readability by\u00a0using spacing\u00a0and\u00a0meaningful naming\u00a0without adding comments. Some of you might be wondering, what\u2019s wrong with comments? …<\/p>\n

Code Readability: Good Comments vs. Bad Comments<\/span> Read More »<\/a><\/p>\n","protected":false},"author":11,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"inline_featured_image":false,"_uag_custom_page_level_css":"","site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"","footnotes":""},"categories":[29],"tags":[207,248,39],"class_list":["post-12055","post","type-post","status-publish","format-standard","hentry","category-low-code","tag-code-readability","tag-comments","tag-filemaker"],"uagb_featured_image_src":{"full":false,"thumbnail":false,"medium":false,"medium_large":false,"large":false,"1536x1536":false,"2048x2048":false,"woocommerce_thumbnail":false,"woocommerce_single":false,"woocommerce_gallery_thumbnail":false},"uagb_author_info":{"display_name":"Weihao Ding","author_link":"https:\/\/www.directimpactsolutions.com\/en\/author\/weihao-dingdirectimpactsolutions-com\/"},"uagb_comment_info":0,"uagb_excerpt":"This article will show examples of good comments vs. bad comments, and how you can improve your code readability by following a few key principles. In our previous blog posts on code readability, we showed how to enhance code readability by\u00a0using spacing\u00a0and\u00a0meaningful naming\u00a0without adding comments. Some of you might be wondering, what\u2019s wrong with comments?…","_links":{"self":[{"href":"https:\/\/www.directimpactsolutions.com\/en\/wp-json\/wp\/v2\/posts\/12055","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.directimpactsolutions.com\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.directimpactsolutions.com\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.directimpactsolutions.com\/en\/wp-json\/wp\/v2\/users\/11"}],"replies":[{"embeddable":true,"href":"https:\/\/www.directimpactsolutions.com\/en\/wp-json\/wp\/v2\/comments?post=12055"}],"version-history":[{"count":4,"href":"https:\/\/www.directimpactsolutions.com\/en\/wp-json\/wp\/v2\/posts\/12055\/revisions"}],"predecessor-version":[{"id":21012,"href":"https:\/\/www.directimpactsolutions.com\/en\/wp-json\/wp\/v2\/posts\/12055\/revisions\/21012"}],"wp:attachment":[{"href":"https:\/\/www.directimpactsolutions.com\/en\/wp-json\/wp\/v2\/media?parent=12055"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.directimpactsolutions.com\/en\/wp-json\/wp\/v2\/categories?post=12055"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.directimpactsolutions.com\/en\/wp-json\/wp\/v2\/tags?post=12055"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}