Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Modern MATLAB codestyle: what is missing? [closed]

I seek to adopt a coding standard for MATLAB, but I am not sure if I picked the right one.

To my best knowledge there is not that much available on topic of programming guidelines for MATLAB, other than this document. The document is well written and has good feedbacks. Standard was published in 2002 (on matlab central) by Richard Johnson but has not being updated since. Is there a more up to date version of it or similar document? (I really failed to google up something else).

Background motivation assumes

  • Coding standards are important
  • Although MATLAB has not change much since 2002, other languages and their approaches have. One could really benefit from those practices.
  • The fact is a lot of people are writing new code using MATLAB or Octave. Although, one would argue the language is virtually dead (blah blah). I would rather not go there (let's mark it as an offtopic).

Why the codestyle is not good enough for me

I'd like to summarize here a few things. If you take time to read the document you might find that it

  • tries to be too hungarian (it's cryptic and I really hate this in most cases)
  • it has too many shortcuts (more less similar to the previous point)
  • it is not supported by Mathworks (but it actually might be a good thing, since all the good stuff in MATLAB came from the user community IMO)
  • there is no automated quality control tools respecting such coding style (here I mean not something like mlint as in *lint family, but more like pep8.py for python)

I guess the reason why such a tool has not been developed is actually the absence of a widely accepted coding standard.

I would really appreciate any of your criticism on the standard or information about a better one.

Do you have any experience on working with this standard? Which parts of it did not work for you? If you never used a formal coding standard but do have a valuable practice that does not fit into it - please provide an example.

like image 674
Yauhen Yakimovich Avatar asked Jul 03 '13 16:07

Yauhen Yakimovich


1 Answers

One of the best answers so far would be to quote a comment by Amro:

"the same author (Richard Johnson)" has published a book 'The Elements of MATLAB Style' (also see wiki) 2011:

cover

Table of Contents

  1. General principles
  2. Formatting
  3. Naming
  4. Documentation
  5. Programming
  6. Files and organization
  7. Development.

Loren has a blog entry with the review of the book. I will just follow here line of comments:

  • 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.

Conclusion

The book seems too general compared to the original document from 2002. I will continue to read it and give more insights, but it does not seem to entirely meet my understanding of strictness required for a coding standard. It mashes a lot of general ideas useful for the beginning programmer, but not strict to program so that they can test code automatically (ones again PEP8).

like image 118
Yauhen Yakimovich Avatar answered Nov 02 '22 13:11

Yauhen Yakimovich