{"id":390,"date":"2016-01-16T02:35:05","date_gmt":"2016-01-16T02:35:05","guid":{"rendered":"https:\/\/blogs.mathworks.com\/developer\/?p=390"},"modified":"2016-01-16T02:35:05","modified_gmt":"2016-01-16T02:35:05","slug":"making-code-usable-useful-and-testable","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/developer\/2016\/01\/16\/making-code-usable-useful-and-testable\/","title":{"rendered":"Making code usable, useful and testable"},"content":{"rendered":"

Writing MATLAB code is seductively easy<\/a>. Polishing the functionality of algorithmic MATLAB code to make it usable, useful and testable requires a bit of design.<\/p>

Taking the spellcheck code that I wrote about earlier<\/a> as a strawman example, it is possible to make that functionality usable, useful and testable by wrapping it as an easy-to-use MATLAB object.<\/p>

Building an API allows more users to use the spellcheck functionality in their code, tools and workflows. In this post, we shall make spellcheck available in MATLAB with an emphasis on making it easy to use.<\/p>

In order to design a usable, useful and testable API, a few high-level design objectives can be articulated as follows:<\/p>

Installation and access to the dependencies should be easy and automated<\/b><\/p>

The spellcheck functionality is enabled by a third party library and while I could write a lot of documentation about what needs to be installed and where it goes, it becomes a lot easier to just use MATLAB to automate this.<\/p>

The class definition for the spellcheck object looks like:<\/p>

classdef<\/span> spellcheck\r\n\r\n    properties<\/span>\r\n        Dictionary;\r\n        CommentsOnly = true;\r\n    end<\/span>\r\n\r\n     properties<\/span>(Hidden)\r\n         Handle;\r\n     end<\/span>\r\n\r\n     % Constructor and methods go here<\/span>\r\n \r\nend<\/span><\/pre>
The properties of this class permits the specification of dictionary files and provides storage for the handle to the Jazzy library. Static methods on this class will return a string specifying where the class is located and this allows download of the library to a known relative location.<\/p>
MATLAB offers a full set of commands to operate on the web and internet. Leveraging these commands, we have:<\/p>
\r\nmethods<\/span>(Static)\r\n\r\n        % SPELLROOT Method that will locate the root folder for tooling<\/span>\r\n        function<\/span> [sRoot] = spellroot()\r\n            % Folder path relative to the location of this code<\/span>\r\n            sRoot = fileparts(mfilename('fullpath'<\/span>));\r\n        end<\/span>\r\n\r\n        % DOWNLOADJAZZY Download and provision the Jazzy library<\/span>\r\n        % Fetches the Java Spell Check library from SourceForge<\/span>\r\n        function<\/span> downloadJazzy()\r\n            % Store the jar file in a known location<\/span>\r\n            jazzyJar = fullfile(spellcheck.spellroot,'lib'<\/span>,'java'<\/span>,'jazzy0-2-1.jar'<\/span>);\r\n            urlwrite('http:\/\/downloads.sourceforge.net\/project\/jazzy\/OldFiles\/jazzy0-2-1.jar'<\/span>,jazzyJar);\r\n            % Add the JAR file to the MATLAB path.<\/span>\r\n            if<\/span> exist(jazzyJar,'file'<\/span>)\r\n                javaaddpath(jazzyJar);\r\n            end<\/span>\r\n        end<\/span>\r\n\r\n    end<\/span>\r\n\r\n<\/pre>
These few lines of code now automates the installation of the library directly from SourceForge to the user's MATLAB session.<\/p>
The real implication is that it took just a few lines of code to empower our MATLAB application with the ability to leverage any of the thousands of projects on SourceForge that may be relevant for the task at hand. The web connectivity and features of the MATLAB platform are not restricted to SourceForge but extends to Github, ProjectLocker, File Exchange, etc.<\/p>
In a nutshell, everything that the internet has to offer are just a few lines of MATLAB code away. MATLAB can just as easily connect to services (REST, SOAP, etc.) but that is a whole other topic.<\/p>
The dictionaries that power the tool can also be fetched from SourceForge. Given that the tool is multi-language capable, we will specify the list of available dictionaries in a neutral format (CSV) for simplicity.<\/p>
en_US.zip, http:\/\/downloads.sourceforge.net\/project\/jazzydicts\/jazzydicts\/Dictionaries%201.0\/en_US.zip\r\nen_NZ.zip, http:\/\/downloads.sourceforge.net\/project\/jazzydicts\/jazzydicts\/Dictionaries%201.0\/en_NZ.zip\r\nen_GB.zip, http:\/\/downloads.sourceforge.net\/project\/jazzydicts\/jazzydicts\/Dictionaries%201.0\/en_GB.zip\r\n<\/pre>
The code for downloading these artifacts is nearly identical to the code for the library and has been omitted from this post for brevity.<\/p>
Given that all our software artifacts are now in place, we can glue them all together. This brings us to our next design objective.<\/p>
The utility should be usable to our diverse user community<\/b><\/p>
MATLAB has evolved over 30 years and has a very diverse user community. From the engineer at an automotive OEM to a researcher in a biotech startup and from a student working on his thesis to a team of software professionals developing MATLAB code on Wall Street, the platform and the language has an amazing diversity in its user base.<\/p>
It is interesting to note that the MATLAB language enables a well designed object to look, feel and work like a typical MATLAB function. In simpler terms, MATLAB classes can do nearly everything your procedural code can do... and some more.<\/p>
To illustrate this, the design of an entry point to our class is the next step in wrapping our functionality.<\/p>
\r\nmethods<\/span>\r\n\r\n        % Constructor<\/span>\r\n        function<\/span> obj = spellcheck(varargin)\r\n\r\n            % Make Jazzy available to MATLAB<\/span>\r\n            import com.mathworks.spellcheck.*<\/span>;\r\n\r\n            % Setup a default language.<\/span>\r\n            obj.Dictionary = which('en_USx.dic'<\/span>); % default<\/span>\r\n\r\n            % Create a jazzy spellchecker<\/span>\r\n            obj.Handle = SpellCheck();\r\n            obj.Handle.setDictionary(obj.Dictionary);\r\n            obj.Handle.verbose = true;\r\n\r\n            % Check and call the spellchecker<\/span>\r\n            if<\/span> nargin==1\r\n\r\n                % Filename specified or string specified<\/span>\r\n                filename = which(varargin{1});\r\n\r\n                % Fire up the spellchecker<\/span>\r\n                if<\/span> isempty(filename)\r\n\r\n                    % We are dealing with a string<\/span>\r\n                    obj.check(varargin{1});\r\n                else<\/span>\r\n                    % We are dealing with a file so read it into a string<\/span>\r\n                    str = fileread(filename);\r\n                    obj.check(str);\r\n                end<\/span>\r\n\r\n            else<\/span>\r\n                % Check the contents of the editor<\/span>\r\n                obj.checkEditor();\r\n            end<\/span>\r\n        end<\/span>\r\n\r\n        % The check() and checkEditor() methods go here<\/span>\r\n    end<\/span>\r\n<\/pre>
The constructor serves as a simple switchyard allowing the user to check strings, files or the contents of the editor depending on the inputs and outputs provided to it. In this case, our constructor with no arguments will check the contents of the editor. This is not always desirable but I have left it this way for illustration purposes.<\/p>
Since, the invocation of the class is identical to the invocation of an identically named MATLAB function, the code provides a familiar interface to users who wish to use this class in their procedural code. Developers who are comfortable with Object Oriented techniques can use the methods of this object for finer grained control over the utility.<\/p>\r\n\r\n
\r\n        % CHECK Method to check an input string<\/span>\r\n        function<\/span> check(obj, inputStr, varargin)\r\n\r\n            % If line number is specified use it for the link<\/span>\r\n            if<\/span> ~isempty(varargin)\r\n                obj.Handle.linenumber = num2str(varargin{1});\r\n                obj.Handle.checkSpelling(inputStr);\r\n            else<\/span>\r\n                obj.Handle.checkSpelling(inputStr);\r\n            end<\/span>\r\n\r\n        end<\/span>\r\n<\/pre>\r\n\r\n
The check() method is where the rubber meets the road. The MATLAB code invokes the Java code and the spelling check is performed. The checkEditor method (omitted for brevity) is similar in that it reads in the current file that is open in the editor and then performs the check.<\/p>
If a linenumber is specified such as in the case of the checkEditor() code, the output includes a hyperlink to the line using the MATLAB opentoline() function.<\/p>
Testing our class:<\/p>\r\n
  >> spellcheck          % Checks the content of the editor\r\n  Input (172): github\r\n\t    No suggestions\r\n  Input (174): API\r\n\t    Suggestion: AP\r\n\t    Suggestion: APB\r\n\t    Suggestion: APO<\/pre>\r\n\r\n
The class now provides me a single command to check the contents of my editor making it trivially accessible as I author content. For example, the dictionary did not contain the word github<\/i> on line 172 or API<\/i> on line 174 of this post.<\/p>
Testing the other routes through the constructor:<\/p>
  >> spellcheck('majic') % Checks string\r\n  >> spellcheck majic    % Equivalent syntax<\/pre>
The spellcheck object can also be instantiated and persisted for finer grain control.<\/p>
  >> s = spellcheck;\r\n  >> s.check('majic');    % Equivalent syntax\r\n\r\n  Input : majic\r\n\t    Suggestion: magic\r\n\t    Suggestion: manic<\/pre>
Is this really multi-language capable? I test the code again setting the dictionary to German.<\/p>
  >> s.Dictionary = 'c:\\Work\\Spellchecker\\public\\de_DE\\de_DEx.dic';\r\n  >> s.check('seprechen sie deutch')  % Intentional spelling mistake\r\n\r\n  Input : seprechen\r\n\t    Suggestion: sprechen\r\n  Input : deutch\r\n\t    Suggestion: deutsch<\/pre>
MATLAB returns the corrected version - \"sprechen sie deutsch\"<\/i> which sounds correct (perhaps a native speaker of the language can confirm).<\/p>
Happy with the way my MATLAB functionality is working, I can finally address the last design requirement.<\/p>
The utility should be testable<\/b><\/p>
In its simplest form, a unit test that exercises the code looks like:<\/p>\r\n
classdef<\/span> testspellcheck < matlab.unittest.TestCase\r\n% TESTSPELLCHECK Simple unit test for our spellcheck<\/span>\r\n    methods<\/span> (Test)\r\n        function<\/span> testSpellCheck(testCase)\r\n\t\ts = spellcheck('majic'<\/span>);\r\n\t\ttestCase.verifyEqual(char(s.Handle.suggestions.elementAt(0)),'magic'<\/span>);\r\n        end<\/span>\r\n    end<\/span>\r\nend<\/span><\/pre>\r\n
I will not go into the details of building a robust regression test suite but rather dwell on the ramifications of the requirement.<\/p>
The construction and use of an automated test suite is a very important part of integrating with 3rd party libraries and products. The test suite isolates our work from upstream dependency changes. If the Jazzy library changes, evolves or is improved upstream, it would naturally affect our functionality.<\/p>
Having a fully automated test suite buys the ability to re-test functionality against upstream changes to the Jazzy library. In this particular case, the code is pretty stable but the reason I write about this is oftentimes, the module upstream is very actively maintained and changes very frequently. In such cases, the investment in building a regression test suite very quickly pays off.<\/p>
In conclusion, as a platform MATLAB is the quintessential melting pot. A variety of technologies and techniques are available right from the language which can be leveraged easily to extend of the platform. As a developer this is useful to know as MATLAB can play well with the best-in-class technologies to create robust solutions with minimal effort.<\/p>