{"id":52,"date":"2006-08-30T08:09:33","date_gmt":"2006-08-30T13:09:33","guid":{"rendered":"https:\/\/blogs.mathworks.com\/loren\/?p=52"},"modified":"2017-08-28T20:14:26","modified_gmt":"2017-08-29T01:14:26","slug":"commenting-code","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/loren\/2006\/08\/30\/commenting-code\/","title":{"rendered":"Commenting Code"},"content":{"rendered":"<div xmlns:mwsh=\"https:\/\/www.mathworks.com\/namespace\/mcode\/v1\/syntaxhighlight.dtd\" class=\"content\">\r\n   <introduction>\r\n      <p>My thesis advisor wanted to cheerfully annihilate me one day many years ago when he was working with a program I wrote.  I\r\n         had a huge set of comments describing the program inputs and outputs, and all the ins and outs of using the program I could\r\n         think of.  Unfortunately for him, the final comment read like this:\r\n      <\/p><pre>   \"Ignore all previous comments; they were for an earlier version of this program.\"<\/pre><p>I have tried to be a better comment citizen ever since.<\/p>\r\n   <\/introduction>\r\n   <h3>Contents<\/h3>\r\n   <div>\r\n      <ul>\r\n         <li><a href=\"#1\">When to Comment<\/a><\/li>\r\n         <li><a href=\"#2\">Help<\/a><\/li>\r\n         <li><a href=\"#3\">Functions<\/a><\/li>\r\n         <li><a href=\"#4\">Algorithms<\/a><\/li>\r\n         <li><a href=\"#5\">Comment Tip<\/a><\/li>\r\n      <\/ul>\r\n   <\/div>\r\n   <h3>When to Comment<a name=\"1\"><\/a><\/h3>\r\n   <p>Here are some of my guidelines for when to insert comments.  Note: I don't always follow my own advice!<\/p>\r\n   <h3>Help<a name=\"2\"><\/a><\/h3>\r\n   <div>\r\n      <ul>\r\n         <li>The H1 line -- the first help line in an M-file, following the function declaration, if the M-file is not a script.<\/li>\r\n         <li>The help body -- the first block of comments in the M-file, contiguous to the H1 line, stating the syntax and usage.  This\r\n            section may contain sections for Limitations, Examples, Class support, and See also references.\r\n         <\/li>\r\n      <\/ul>\r\n   <\/div>\r\n   <h3>Functions<a name=\"3\"><\/a><\/h3>\r\n   <div>\r\n      <ul>\r\n         <li>An H1 line for each subfunction.  I don't, however, necessarily feel the same way about nested functions, depending on their\r\n            usage.<\/li>\r\n         <li>The final <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/ref\/end.html\"><tt>end<\/tt><\/a> statement of each function, if used, and certainly when nested functions are in the file.\r\n         <\/li>\r\n         <li>In <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/function-handles.html\">nested functions<\/a>, when a variable is likely to be changed from code elsewhere in the file. This way, I am more likely to understand what I'm\r\n            seeing when I debug.\r\n         <\/li>\r\n      <\/ul>\r\n   <\/div>\r\n   <h3>Algorithms<a name=\"4\"><\/a><\/h3>\r\n   <div>\r\n      <ul>\r\n         <li>A description of each logical chunk of code, especially when an algorithm has many steps.<\/li>\r\n         <li>Equivalent M-code or perhaps code in some other language, especially if some code is potentially very obscure or dense.  An\r\n            example might be to show the explicit <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/ref\/for.html\"><tt>for<\/tt>-loop<\/a> equivalent code versus the vectorized expression.\r\n         <\/li>\r\n      <\/ul>\r\n   <\/div>\r\n   <h3>Comment Tip<a name=\"5\"><\/a><\/h3>\r\n   <p>Block comments can be very useful for placing comments in the middle of a multi-line statement or expression in MATLAB.   Sometimes I end\r\n      up with a long list of properties I think I want to change in plot.\r\n   <\/p><pre style=\"background: #F9F7F3; padding: 10px; border: 1px solid rgb(200,200,200)\">type <span style=\"color: #A020F0\">hgComments<\/span>\r\nhgComments<\/pre><pre style=\"font-style:oblique\">\r\n% Base script to illustrate block comments.\r\n\r\nt = pi:pi\/20:5*pi;\r\nsinc = sin(30*t).\/t;\r\nh = plot(t,sinc);\r\nset(h,...\r\n    'linestyle','--',...\r\n    'color','m',...\r\n    'marker','diamond',...\r\n    'markersize',8,...\r\n    'markerfacecolor','c',...\r\n    'markeredgecolor','b'...\r\n    )\r\n    \r\n<\/pre><img decoding=\"async\" vspace=\"5\" hspace=\"5\" src=\"https:\/\/blogs.mathworks.com\/images\/loren\/52\/commentingCode_01.png\"> <p>If I try to just comment out the line setting the <tt>MarkerFaceColor<\/tt> property, I find that the editor shows me an <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/ref\/mlint.html\"><tt>mlint<\/tt><\/a> message.\r\n   <\/p><pre style=\"background: #F9F7F3; padding: 10px; border: 1px solid rgb(200,200,200)\">dbtype <span style=\"color: #A020F0\">hgCommentsBad<\/span><\/pre><pre style=\"font-style:oblique\">\r\n1     % Script to illustrate misuse of comments within a statement.\r\n2     \r\n3     t = pi:pi\/20:5*pi;\r\n4     sinc = sin(30*t).\/t;\r\n5     h = plot(t,sinc)\r\n6     set(h,...\r\n7         'linestyle','--',...\r\n8         'color','m',...\r\n9         'marker','diamond',...\r\n10        'markersize',8,...\r\n11    %    'markerfacecolor','c',...\r\n12        'markeredgecolor','b'...\r\n13        )\r\n14        \r\n<\/pre><pre style=\"background: #F9F7F3; padding: 10px; border: 1px solid rgb(200,200,200)\">info = mlint(<span style=\"color: #A020F0\">'hgCommentsBad'<\/span>);\r\ninfo.message<\/pre><pre style=\"font-style:oblique\">ans =\r\nTerminate statement with semicolon to suppress output.\r\nans =\r\nThere may be a parenthesis imbalance around here.\r\nans =\r\nTerminate statement with semicolon to suppress output.\r\nans =\r\nThere may be a parenthesis imbalance around here.\r\n<\/pre><pre style=\"background: #F9F7F3; padding: 10px; border: 1px solid rgb(200,200,200)\"><span style=\"color: #0000FF\">try<\/span>\r\n    hgCommentsBad\r\n<span style=\"color: #0000FF\">catch<\/span>\r\n    l = lasterror();\r\n    disp(l.message)\r\n<span style=\"color: #0000FF\">end<\/span><\/pre><pre style=\"font-style:oblique\">Error: File: H:\\Documents\\LOREN\\MyJob\\Art of MATLAB\\hgCommentsBad.m Line: 11 Column: 31\r\nExpression or statement is incorrect--possibly unbalanced (, {, or [.\r\n<\/pre><p>Instead I can use block comments to achieve the goal of not setting the property in the middle of my list, without deleting\r\n      the code, until I am sure that's the change I want.\r\n   <\/p><pre style=\"background: #F9F7F3; padding: 10px; border: 1px solid rgb(200,200,200)\">dbtype <span style=\"color: #A020F0\">hgCommentsGood<\/span><\/pre><pre style=\"font-style:oblique\">\r\n1     % Script to illustrate block comments.\r\n2     \r\n3     t = pi:pi\/20:5*pi;\r\n4     sinc = sin(30*t).\/t;\r\n5     h = plot(t,sinc);\r\n6     set(h,...\r\n7         'linestyle','--',...\r\n8         'color','m',...\r\n9         'marker','diamond',...\r\n10        'markersize',8,...\r\n11    %{\r\n12        'markerfacecolor','c',...\r\n13    %}\r\n14        'markeredgecolor','b'...\r\n15        )\r\n16        \r\n<\/pre><pre style=\"background: #F9F7F3; padding: 10px; border: 1px solid rgb(200,200,200)\">info = mlint(<span style=\"color: #A020F0\">'hgCommentsGood'<\/span>);\r\ninfo.message<\/pre><pre style=\"background: #F9F7F3; padding: 10px; border: 1px solid rgb(200,200,200)\">hgCommentsGood<\/pre><img decoding=\"async\" vspace=\"5\" hspace=\"5\" src=\"https:\/\/blogs.mathworks.com\/images\/loren\/52\/commentingCode_02.png\"> <p>Can you see yourself using block comments to help you with some of your programming tasks?  <a href=\"?p=52#respond\">Let me know.<\/a><\/p>\r\n   <p style=\"text-align: right; font-size: xx-small; font-weight:lighter;   font-style: italic; color: gray\"><br>\r\n      Published with MATLAB&reg; 7.3<br><\/p>\r\n<\/div>\r\n<!--\r\n##### SOURCE BEGIN #####\r\n%% Commenting Code\r\n% My thesis advisor wanted to cheerfully annihilate me one day many years\r\n% ago when he was working with a program I wrote.  I had a huge set of\r\n% comments describing the program inputs and outputs, and all the ins and\r\n% outs of using the program I could think of.  Unfortunately for him, the\r\n% final comment read like this: \r\n%\r\n%     \"Ignore all previous comments; they were for an earlier version of this program.\"  \r\n%\r\n% I have tried to be a better comment citizen ever since.\r\n%% When to Comment\r\n% Here are some of my guidelines for when to insert comments.  Note: I\r\n% don't always follow my own advice!\r\n%% Help\r\n%\r\n% * The H1 line REPLACE_WITH_DASH_DASH the first help line in an M-file, following the function\r\n% declaration, if the M-file is not a script. \r\n% * The help body REPLACE_WITH_DASH_DASH the first\r\n% block of comments in the M-file, contiguous to the H1 line, stating the\r\n% syntax and usage.  This section may contain sections for Limitations,\r\n% Examples, Class support, and See also references.\r\n%% Functions\r\n%\r\n% * An H1 line for each subfunction.  I don't, however,\r\n% necessarily feel the same way about nested functions, depending on their\r\n% usage.  <?p=52#respond What do you think?>\r\n% * The final\r\n% <https:\/\/www.mathworks.com\/help\/matlab\/ref\/end.html |end|>\r\n% statement of each function, if used, and certainly when nested functions\r\n% are in the file.\r\n% * In <https:\/\/www.mathworks.com\/access\/helpdesk\/help\/techdoc\/ref\/function_handle.html nested functions>,\r\n% when a variable is likely to be changed from code elsewhere in the file.\r\n% This way, I am more likely to understand what I'm seeing when I debug.\r\n%% Algorithms\r\n%\r\n% * A description of each logical chunk of code, especially when an\r\n% algorithm has many steps.\r\n% * Equivalent M-code or perhaps code in some other language, especially if\r\n% some code is potentially very obscure or dense.  An example might be to\r\n% show the explicit\r\n% <https:\/\/www.mathworks.com\/help\/matlab\/ref\/for.html |for|-loop>\r\n% equivalent code versus the vectorized expression.\r\n%% Comment Tip\r\n% <https:\/\/www.mathworks.com\/access\/helpdesk\/help\/techdoc\/rn\/r14_v7_env16.html#1013865 Block comments>\r\n% can be very useful for placing comments in the middle of a multi-line\r\n% statement or expression in MATLAB.   Sometimes I end up with a long list\r\n% of properties I think I want to change in plot.\r\ntype hgComments\r\nhgComments\r\n%%\r\n% If I try to just comment out the line setting the |MarkerFaceColor|\r\n% property, I find that the editor shows me an \r\n% <https:\/\/www.mathworks.com\/help\/matlab\/ref\/mlint.html |mlint|>\r\n% message.\r\ndbtype hgCommentsBad\r\n%%\r\ninfo = mlint('hgCommentsBad');\r\ninfo.message\r\n%%\r\ntry\r\n    hgCommentsBad\r\ncatch\r\n    l = lasterror();\r\n    disp(l.message)\r\nend\r\n%%\r\n% Instead I can use block comments to achieve the goal of not setting the\r\n% property in the middle of my list, without deleting the code, until I am\r\n% sure that's the change I want.\r\ndbtype hgCommentsGood\r\n%%\r\ninfo = mlint('hgCommentsGood');\r\ninfo.message\r\n%%\r\nhgCommentsGood\r\n%%\r\n% Can you see yourself using block comments to help you with some of your\r\n% programming tasks?  <?p=52#respond Let me know.>\r\n\r\n##### SOURCE END #####\r\n-->","protected":false},"excerpt":{"rendered":"<p>\r\n   \r\n      My thesis advisor wanted to cheerfully annihilate me one day many years ago when he was working with a program I wrote.  I\r\n         had a huge set of comments describing the... <a class=\"read-more\" href=\"https:\/\/blogs.mathworks.com\/loren\/2006\/08\/30\/commenting-code\/\">read more >><\/a><\/p>","protected":false},"author":39,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[16,15],"tags":[],"_links":{"self":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/52"}],"collection":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/users\/39"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/comments?post=52"}],"version-history":[{"count":3,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/52\/revisions"}],"predecessor-version":[{"id":2406,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/52\/revisions\/2406"}],"wp:attachment":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/media?parent=52"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/categories?post=52"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/tags?post=52"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}