Book Review: The Elements of MATLAB Style
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 what's important in the eyes of one particular prolific MATLAB user. And it's a book worth you investigating for questions of style, especially if you work in a group or organization where there is lots of shared code and lots of people looking at and using the code.
The first thing I like about Richard's book is the intent, to make it a reference in the venerable tradition of The Elements of Style, by Strunk and White. If you write in English, I highly recommend this book. Neither book is comprehensive but rather attempts 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 & pitfalls, and conventions (some, but not all, particular to MATLAB).
Taking a look at the table of contents, we see first some high level principles, followed by a small number of main topics:
- Formatting
- Naming
- Documentation
- Programming
- Files and Organization
- Development
with a few helpful lists bringing up the rear (e.g., keywords).
Each of these chapters ends with a summary section which pulls together the main themes of each section. These summaries 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 will be some items in the chapter to guide you.
I don't happen to agree with every choice Richard has made in terms of conventions, e.g., for layout or formatting. Nor does MathWorks follow all of these (or all of any convention, in some cases). I do agree that he has identified relevant topics worthy of any group embarking on a project to discuss and standardize on.
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, so don't read anything into ones that I have not listed here!
- #7 Split Long Code Lines at Graceful Points - 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.
- # 10 Do Not Use Hard Tabs - This helps keep sanity when working among a group with possibly different editing environments.
- # 43 Use Meaningful Names for Variables with a Large Scope - This makes code much easier to read, understand, and debug, if necessary.
- # 69 Name Functions for What They Do - Since functions perform an action, the name should include information about the action.
- # 86 Use Sortable Numbering in Data Filesnames - If you have many similar files of data, having a rational numbering scheme can only help you out.
- # 97 Be Sure That Comments Agree with the Code - I will never forget the time that my thesis advisor called me because he was really irritated. I had left him a copy of a Fortran program that had copious comments, the final one being "Ignore all the comments above; they were for a previous version."
- # 135 Avoid Cryptic Code - I have found that generally, writing cryptic code buys less than I expect in terms of good things, and more headaches than it warrants. On occasion, I have used cryptic code for performance in something time-critical. When I do, I try to comment it fully, including a straight-forward implementation in the comments which I have tested. That way, when the performance trade-offs change, I understand what the code is supposed to do and have two starting options for doing a code update.
- # 150, 151 Minimize the Use of Global Variables and Minimize the Use of Global Constants -- I would say this even more strongly myself. There are superior techniques for dealing with information you want to share, whether they be function handles, classes and their properties, or some other methods. These techniques are much safer to use for many reasons - e.g., more easily controlled side effects, should any be desired, and code becomes more suitable for parallelism potentially.
- # 172 Use Parenthese - Clarity of meaning is paramount, especially if others need to understand, modify, or translate the code.
- # 176 Avoid Use of eval When Possible - I'm sure it doesn't seem so to some MATLAB users, but eval is avoidable most of the time.
- # 185-188 The first of these is Avoid Complicated Conditional Expressions - These entries contain some useful thoughts on dealing with conditional constructs, the ordering of the cases, etc.
- # 271-275 The first of these is Write Small Tests - I love that Richard has made testing a central tenet of this style guide. I don't see how programmers function well without a robust test suite.
Congratulations to Richard for writing "The Elements of MATLAB Style." It's a book that I recommend you read. I encourage you to adapt the guidelines in a way suitable for your programming environment.
- Category:
- Best Practice,
- News
