{"id":265,"date":"2011-02-10T19:56:08","date_gmt":"2011-02-10T19:56:08","guid":{"rendered":"https:\/\/blogs.mathworks.com\/loren\/2011\/02\/10\/book-review-the-elements-of-matlab-style\/"},"modified":"2011-02-10T21:06:56","modified_gmt":"2011-02-10T21:06:56","slug":"book-review-the-elements-of-matlab-style","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/loren\/2011\/02\/10\/book-review-the-elements-of-matlab-style\/","title":{"rendered":"Book Review: The Elements of MATLAB Style"},"content":{"rendered":"<div xmlns:mwsh=\"https:\/\/www.mathworks.com\/namespace\/mcode\/v1\/syntaxhighlight.dtd\" class=\"content\">\r\n   <introduction>\r\n      <p>I've recently been offered the opportunity to review a new book, <a href=\"http:\/\/www.cambridge.org\/us\/knowledge\/isbn\/item5745060\/?site_locale=en_US\">The Elements of MATLAB Style<\/a> by contributor to the FEX, <a href=\"https:\/\/www.mathworks.com\/matlabcentral\/fileexchange\/authors\/6765\">Richard K. Johnson<\/a>.  It's a great opportunity for me to see what's important in the eyes of one particular prolific MATLAB user.  And it's a\r\n         book worth you investigating for questions of style, especially if you work in a group or organization where there is lots\r\n         of shared code and lots of people looking at and using the code.\r\n      <\/p>\r\n   <\/introduction>\r\n   <p>The first thing I like about Richard's book is the intent, to make it a reference in the venerable tradition of <a href=\"http:\/\/en.wikipedia.org\/wiki\/The_Elements_of_Style\">The Elements of Style<\/a>, by Strunk and White.  If you write in English, I highly recommend this book.  Neither book is comprehensive but rather attempts\r\n      to boil ideas down to the ones with the largest pay-off and the ones where mistakes are often made.  So you get some essentials\r\n      &amp; pitfalls, and conventions (some, but not all, particular to MATLAB).\r\n   <\/p>\r\n   <p>Taking a look at the table of contents, we see first some high level principles, followed by a small number of main topics:<\/p>\r\n   <div>\r\n      <ul>\r\n         <li>Formatting<\/li>\r\n         <li>Naming<\/li>\r\n         <li>Documentation<\/li>\r\n         <li>Programming<\/li>\r\n         <li>Files and Organization<\/li>\r\n         <li>Development<\/li>\r\n      <\/ul>\r\n   <\/div>\r\n   <p>with a few helpful lists bringing up the rear (e.g., <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2010b\/techdoc\/ref\/iskeyword.html\">keywords<\/a>).\r\n   <\/p>\r\n   <p>Each of these chapters ends with a summary section which pulls together the main themes of each section.  These summaries\r\n      serve as a helpful review when you want to go back to look for more information.  If it's listed there, you can be sure there\r\n      will be some items in the chapter to guide you.\r\n   <\/p>\r\n   <p>I don't happen to agree with every choice Richard has made in terms of conventions, e.g., for layout or formatting.  Nor does\r\n      MathWorks follow all of these (or all of any convention, in some cases).  I do agree that he has identified relevant topics\r\n      worthy of any group embarking on a project to discuss and standardize on.\r\n   <\/p>\r\n   <p>I'd now like to take a little time mentioning a few of many points from the book that resonate for me.  These are only a sampling,\r\n      so don't read anything into ones that I have not listed here!\r\n   <\/p>\r\n   <div>\r\n      <ul>\r\n         <li>#7 <i>Split Long Code Lines at Graceful Points<\/i> - I find this one useful as it is a total pain having to trail far off to the right in any editor, even though it is possible.\r\n         <\/li>\r\n         <li>#  10 <i>Do Not Use Hard Tabs<\/i> - This helps keep sanity when working among a group with possibly different editing environments.\r\n         <\/li>\r\n         <li>#  43 <i>Use Meaningful Names for Variables with a Large Scope<\/i> - This makes code much easier to read, understand, and debug, if necessary.\r\n         <\/li>\r\n         <li>#  69 <i>Name Functions for What They Do<\/i> - Since functions perform an action, the name should include information about the action.\r\n         <\/li>\r\n         <li>#  86 <i>Use Sortable Numbering in Data Filesnames<\/i> - If you have many similar files of data, having a rational numbering scheme can only help you out.\r\n         <\/li>\r\n         <li>#  97 <i>Be Sure That Comments Agree with the Code<\/i> - I will never forget the time that my thesis advisor called me because he was really irritated.  I had left him a copy of\r\n            a Fortran program that had copious comments, the final one being \"Ignore all the comments above; they were for a previous\r\n            version.\"\r\n         <\/li>\r\n         <li># 135 <i>Avoid Cryptic Code<\/i> - I have found that generally, writing cryptic code buys less than I expect in terms of good things, and more headaches than\r\n            it warrants.  On occasion, I have used cryptic code for performance in something time-critical.  When I do, I try to comment\r\n            it fully, including a straight-forward implementation in the comments which I have tested. That way, when the performance\r\n            trade-offs change, I understand what the code is supposed to do and have two starting options for doing a code update.\r\n         <\/li>\r\n         <li># 150, 151 <i>Minimize the Use of Global Variables<\/i> and <i>Minimize the Use of Global Constants<\/i> -- I would say this even more strongly myself. There are superior techniques for dealing with information you want to share,\r\n            whether they be function handles, classes and their properties, or some other methods.  These techniques are much safer to\r\n            use for many reasons - e.g., more easily controlled side effects, should any be desired, and code becomes more suitable for\r\n            parallelism potentially.\r\n         <\/li>\r\n         <li># 172 <i>Use Parenthese<\/i> - Clarity of meaning is paramount, especially if others need to understand, modify, or translate the code.\r\n         <\/li>\r\n         <li># 176 <i>Avoid Use of <tt>eval<\/tt> When Possible<\/i> - I'm sure it doesn't seem so to some MATLAB users, but <tt>eval<\/tt> is avoidable <b>most<\/b> of the time.\r\n         <\/li>\r\n         <li># 185-188 The first of these is <i>Avoid Complicated Conditional Expressions<\/i> - These entries contain some useful thoughts on dealing with conditional constructs, the ordering of the cases, etc.\r\n         <\/li>\r\n         <li># 271-275 The first of these is <i>Write Small Tests<\/i> - I love that Richard has made testing a central tenet of this style guide.  I don't see how programmers function well without\r\n            a robust test suite.\r\n         <\/li>\r\n      <\/ul>\r\n   <\/div>\r\n   <p>Congratulations to Richard for writing \"The Elements of MATLAB Style.\" It's a book that I recommend you read.  I encourage\r\n      you to adapt the guidelines in a way suitable for your programming environment.\r\n   <\/p><script language=\"JavaScript\">\r\n<!--\r\n\r\n    function grabCode_e767ae67614c4e729a7ac511721ee6fa() {\r\n        \/\/ Remember the title so we can use it in the new page\r\n        title = document.title;\r\n\r\n        \/\/ Break up these strings so that their presence\r\n        \/\/ in the Javascript doesn't mess up the search for\r\n        \/\/ the MATLAB code.\r\n        t1='e767ae67614c4e729a7ac511721ee6fa ' + '##### ' + 'SOURCE BEGIN' + ' #####';\r\n        t2='##### ' + 'SOURCE END' + ' #####' + ' e767ae67614c4e729a7ac511721ee6fa';\r\n    \r\n        b=document.getElementsByTagName('body')[0];\r\n        i1=b.innerHTML.indexOf(t1)+t1.length;\r\n        i2=b.innerHTML.indexOf(t2);\r\n \r\n        code_string = b.innerHTML.substring(i1, i2);\r\n        code_string = code_string.replace(\/REPLACE_WITH_DASH_DASH\/g,'--');\r\n\r\n        \/\/ Use \/x3C\/g instead of the less-than character to avoid errors \r\n        \/\/ in the XML parser.\r\n        \/\/ Use '\\x26#60;' instead of '<' so that the XML parser\r\n        \/\/ doesn't go ahead and substitute the less-than character. \r\n        code_string = code_string.replace(\/\\x3C\/g, '\\x26#60;');\r\n\r\n        author = 'Loren Shure';\r\n        copyright = 'Copyright 2011 The MathWorks, Inc.';\r\n\r\n        w = window.open();\r\n        d = w.document;\r\n        d.write('<pre>\\n');\r\n        d.write(code_string);\r\n\r\n        \/\/ Add author and copyright lines at the bottom if specified.\r\n        if ((author.length > 0) || (copyright.length > 0)) {\r\n            d.writeln('');\r\n            d.writeln('%%');\r\n            if (author.length > 0) {\r\n                d.writeln('% _' + author + '_');\r\n            }\r\n            if (copyright.length > 0) {\r\n                d.writeln('% _' + copyright + '_');\r\n            }\r\n        }\r\n\r\n        d.write('<\/pre>\\n');\r\n      \r\n      d.title = title + ' (MATLAB code)';\r\n      d.close();\r\n      }   \r\n      \r\n-->\r\n<\/script><p style=\"text-align: right; font-size: xx-small; font-weight:lighter;   font-style: italic; color: gray\"><br><a href=\"javascript:grabCode_e767ae67614c4e729a7ac511721ee6fa()\"><span style=\"font-size: x-small;        font-style: italic;\">Get \r\n            the MATLAB code \r\n            <noscript>(requires JavaScript)<\/noscript><\/span><\/a><br><br>\r\n      Published with MATLAB&reg; 7.11<br><\/p>\r\n<\/div>\r\n<!--\r\ne767ae67614c4e729a7ac511721ee6fa ##### SOURCE BEGIN #####\r\n%% Book Review: The Elements of MATLAB Style\r\n% I've recently been offered the opportunity to review a new book,\r\n% <http:\/\/www.cambridge.org\/us\/knowledge\/isbn\/item5745060\/?site_locale=en_US\r\n% The Elements of MATLAB Style> by contributor to the FEX,\r\n% <https:\/\/www.mathworks.com\/matlabcentral\/fileexchange\/authors\/6765 Richard\r\n% K. Johnson>.  It's a great opportunity for me to see what's important in\r\n% the eyes of one particular prolific MATLAB user.  And it's a book worth\r\n% you investigating for questions of style, especially if you work in a\r\n% group or organization where there is lots of shared code and lots of\r\n% people looking at and using the code.\r\n%%\r\n% The first thing I like about Richard's book is the intent, to make it a\r\n% reference in the venerable tradition of\r\n% <http:\/\/en.wikipedia.org\/wiki\/The_Elements_of_Style The Elements of\r\n% Style>, by Strunk and White.  If you write in English, I highly recommend\r\n% this book.  Neither book is comprehensive but rather attempts to boil\r\n% ideas down to the ones with the largest pay-off and the ones where\r\n% mistakes are often made.  So you get some essentials & pitfalls, and\r\n% conventions (some, but not all, particular to MATLAB).\r\n%%\r\n% Taking a look at the table of contents, we see first some high level\r\n% principles, followed by a small number of main topics:\r\n%\r\n% * Formatting\r\n% * Naming\r\n% * Documentation\r\n% * Programming\r\n% * Files and Organization\r\n% * Development\r\n%\r\n% with a few helpful lists bringing up the rear (e.g.,\r\n% <https:\/\/www.mathworks.com\/help\/releases\/R2010b\/techdoc\/ref\/iskeyword.html\r\n% keywords>).\r\n%%\r\n% Each of these chapters ends with a summary section which pulls together\r\n% the main themes of each section.  These summaries serve as a helpful\r\n% review when you want to go back to look for more information.  If it's\r\n% listed there, you can be sure there will be some items in the chapter to\r\n% guide you.\r\n%%\r\n% I don't happen to agree with every choice Richard has made in terms of\r\n% conventions, e.g., for layout or formatting.  Nor does MathWorks follow\r\n% all of these (or all of any convention, in some cases).  I do agree that\r\n% he has identified relevant topics worthy of any group embarking on a\r\n% project to discuss and standardize on.\r\n%%\r\n% I'd now like to take a little time mentioning a few of many points from\r\n% the book that resonate for me.  These are only a sampling, so don't read\r\n% anything into ones that I have not listed here!\r\n%\r\n% * #7 _Split Long Code Lines at Graceful Points_ - I find this one useful\r\n% as it is a total pain having to trail far off to the right in any editor,\r\n% even though it is possible.\r\n% * #  10 _Do Not Use Hard Tabs_ - This helps keep sanity when working among\r\n% a group with possibly different editing environments.\r\n% * #  43 _Use Meaningful Names for Variables with a Large Scope_ - This\r\n% makes code much easier to read, understand, and debug, if necessary.\r\n% * #  69 _Name Functions for What They Do_ - Since functions perform an\r\n% action, the name should include information about the action.\r\n% * #  86 _Use Sortable Numbering in Data Filesnames_ - If you have many\r\n% similar files of data, having a rational numbering scheme can only help\r\n% you out.\r\n% * #  97 _Be Sure That Comments Agree with the Code_ - I will never forget\r\n% the time that my thesis advisor called me because he was really\r\n% irritated.  I had left him a copy of a Fortran program that had copious\r\n% comments, the final one being \"Ignore all the comments above; they were\r\n% for a previous version.\" \r\n% * # 135 _Avoid Cryptic Code_ - I have found that generally, writing\r\n% cryptic code buys less than I expect in terms of good things, and more\r\n% headaches than it warrants.  On occasion, I have used cryptic code for\r\n% performance in something time-critical.  When I do, I try to comment it\r\n% fully, including a straight-forward implementation in the comments which\r\n% I have tested. That way, when the performance trade-offs change, I\r\n% understand what the code is supposed to do and have two starting options\r\n% for doing a code update.\r\n% * # 150, 151 _Minimize the Use of Global Variables_ and _Minimize the Use\r\n% of Global Constants_ REPLACE_WITH_DASH_DASH I would say this even more strongly myself. There\r\n% are superior techniques for dealing with information you want to share,\r\n% whether they be function handles, classes and their properties, or some\r\n% other methods.  These techniques are much safer to use for many reasons -\r\n% e.g., more easily controlled side effects, should any be desired, and\r\n% code becomes more suitable for parallelism potentially.\r\n% * # 172 _Use Parenthese_ - Clarity of meaning is paramount, especially if\r\n% others need to understand, modify, or translate the code.\r\n% * # 176 _Avoid Use of |eval| When Possible_ - I'm sure to some it doesn't\r\n% seem so to some MATLAB users, but |eval| is avoidable *most* of the time.\r\n% * # 185-188 The first of these is _Avoid Complicated Conditional\r\n% Expressions_ - These entries contain some useful thoughts on dealing with\r\n% conditional constructs, the ordering of the cases, etc.\r\n% * # 271-275 The first of these is _Write Small Tests_ - I love that\r\n% Richard has made testing a central tenet of this style guide.  I don't\r\n% see how programmers function well without a robust test suite.\r\n%\r\n%%\r\n% Congratulations to Richard for writing \"The Elements of MATLAB Style.\"\r\n% It's a book that I recommend you read.  I encourage you to adapt the\r\n% guidelines in a way suitable for your programming environment.\r\n##### SOURCE END ##### e767ae67614c4e729a7ac511721ee6fa\r\n-->","protected":false},"excerpt":{"rendered":"<p>\r\n   \r\n      I've recently been offered the opportunity to review a new book, The Elements of MATLAB Style by contributor to the FEX, Richard K. Johnson.  It's a great opportunity for me to see... <a class=\"read-more\" href=\"https:\/\/blogs.mathworks.com\/loren\/2011\/02\/10\/book-review-the-elements-of-matlab-style\/\">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,40],"tags":[],"_links":{"self":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/265"}],"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=265"}],"version-history":[{"count":0,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/265\/revisions"}],"wp:attachment":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/media?parent=265"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/categories?post=265"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/tags?post=265"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}