{"id":105,"date":"2025-08-30T04:49:01","date_gmt":"2025-08-30T04:49:01","guid":{"rendered":"http:\/\/katzcs.com\/?page_id=105"},"modified":"2025-08-30T04:49:15","modified_gmt":"2025-08-30T04:49:15","slug":"readability-comments","status":"publish","type":"page","link":"http:\/\/katzcs.com\/?page_id=105","title":{"rendered":"Readability &#8211; Comments"},"content":{"rendered":"\n<div style=\"height:13px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<h1 class=\"wp-block-heading has-text-align-center\">Readability Expectations<\/h1>\n\n\n\n<div style=\"height:16px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<h2 class=\"wp-block-heading has-text-align-center\">Comments<\/h2>\n\n\n\n<div style=\"height:16px\" aria-hidden=\"true\" class=\"wp-block-spacer\"><\/div>\n\n\n\n<div class=\"wp-block-group has-tertiary-background-color has-background has-global-padding is-layout-constrained wp-block-group-is-layout-constrained\" style=\"margin-top:0;margin-bottom:0;padding-top:var(--wp--preset--spacing--50);padding-bottom:var(--wp--preset--spacing--50)\">\n<p>Comments are a means of communication. They are the notes that a programmer makes to themselves and to any other programmer that may look at their code.<\/p>\n\n\n\n<p>Here are some general commenting suggestions:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>If you have any blocks of logic or sections with multiple conditionals you should have comments with some explanation as to what the code is supposed to do.<\/li>\n\n\n\n<li>You should also put a comment before each function. This comment should explain what the function does and any arguments \/ return values. (Exception: If the function is a simple getter\/setter in a class then an explanatory comment is not needed.)\n<ul class=\"wp-block-list\">\n<li><pre class=\"wp-block-preformatted\">\/\/ Searches for an element in the list and returns its index<br>\/\/ Returns -1 if elt is null or elt is not in list<br>public int indexOf(E elt){ \/*code*\/ }<\/pre><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n<ul class=\"wp-block-list\">\n<li>While <a href=\"http:\/\/katzcs.com\/?page_id=100\" data-type=\"page\" data-id=\"100\">all variables should be named meaningfully<\/a>, it may be helpful to add a comment at the initial creation of a variable with further explanation of what it means and when it will be used.\n<ul class=\"wp-block-list\">\n<li><pre class=\"wp-block-preformatted\">int max_x; \/\/ variable to contain the largest x coordinate visible on the window<\/pre><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n<ul class=\"wp-block-list\">\n<li>In higher-level languages it is not necessary to comment everything. We don&#8217;t want to clutter up code with unneeded comments such as: \n<ul class=\"wp-block-list\">\n<li><pre class=\"wp-block-preformatted\">int j = 12; \/\/assigning value 12 to variable j<br>if ( j &lt;= 0 ) \/\/ test to see if j is less than or equal to zero, if so execute the next block of code<\/pre><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Since comments are meant as a means of communication, they should be relatively free of typos.<\/li>\n<\/ul>\n\n\n\n<p><\/p>\n\n\n\n<p>While your program is a work in progress, comments are a good place to make notes about what tasks have been completed and what has to be done. If you are trying to resolve a bug you can also keep notes in place about how you have tried to fix it.<\/p>\n\n\n\n<p>Ideally, you comment while you are coding but cleaning up (and perhaps adding) comments is often a good step to take before finalizing a project. The comments should match the current state of the code.<\/p>\n<\/div>\n\n\n\n<p>Be aware: These are my opinions. Other instructors will have their own policies! <\/p>\n\n\n<div class=\"wp-block-post-date__modified-date wp-block-post-date\"><time datetime=\"2025-08-30T04:49:15+00:00\">August 30, 2025<\/time><\/div>\n\n\n<div class=\"wp-block-group has-global-padding is-layout-constrained wp-container-core-group-is-layout-b2082ebc wp-block-group-is-layout-constrained\" style=\"margin-top:0;margin-bottom:0;padding-top:100px;padding-right:20px;padding-bottom:100px;padding-left:20px\">\n<div class=\"wp-block-columns are-vertically-aligned-center is-layout-flex wp-container-core-columns-is-layout-9cad5244 wp-block-columns-is-layout-flex\" style=\"margin-top:0;margin-bottom:0\">\n<div class=\"wp-block-column is-vertically-aligned-center is-layout-flow wp-block-column-is-layout-flow\">\n<p>Check out more of my readability expectations by language:<\/p>\n<\/div>\n\n\n\n<div class=\"wp-block-column is-vertically-aligned-center is-layout-flow wp-block-column-is-layout-flow\">\n<div class=\"wp-block-buttons is-content-justification-space-between is-layout-flex wp-container-core-buttons-is-layout-8f3c3dcc wp-block-buttons-is-layout-flex\" style=\"margin-top:40px\">\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-primary-background-color has-background wp-element-button\" style=\"border-radius:0px\">C++<\/a><\/div>\n\n\n\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-primary-background-color has-background wp-element-button\" style=\"border-radius:0px\">Java<\/a><\/div>\n\n\n\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-primary-background-color has-background wp-element-button\" style=\"border-radius:0px\">Python<\/a><\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n","protected":false},"excerpt":{"rendered":"<p>Readability Expectations Comments Comments are a means of communication. They are the notes that a programmer makes to themselves and to any other programmer that may look at their code. Here are some general commenting suggestions: While your program is a work in progress, comments are a good place to make notes about what tasks [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"parent":82,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-105","page","type-page","status-publish","hentry"],"jetpack_sharing_enabled":true,"_links":{"self":[{"href":"http:\/\/katzcs.com\/index.php?rest_route=\/wp\/v2\/pages\/105","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/katzcs.com\/index.php?rest_route=\/wp\/v2\/pages"}],"about":[{"href":"http:\/\/katzcs.com\/index.php?rest_route=\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"http:\/\/katzcs.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/katzcs.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=105"}],"version-history":[{"count":2,"href":"http:\/\/katzcs.com\/index.php?rest_route=\/wp\/v2\/pages\/105\/revisions"}],"predecessor-version":[{"id":107,"href":"http:\/\/katzcs.com\/index.php?rest_route=\/wp\/v2\/pages\/105\/revisions\/107"}],"up":[{"embeddable":true,"href":"http:\/\/katzcs.com\/index.php?rest_route=\/wp\/v2\/pages\/82"}],"wp:attachment":[{"href":"http:\/\/katzcs.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=105"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}