<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<font face="Arial">Hello devs,<br>
<br>
The so-called <i>slint </i>module is a new experimental tool
proposed and somewhat documented in Scilab master: <a
class="moz-txt-link-freetext"
href="http://www.scilab.org/fr/development/nightly_builds/master"><a class="moz-txt-link-freetext" href="http://www.scilab.org/fr/development/nightly_builds/master">http://www.scilab.org/fr/development/nightly_builds/master</a></a><br>
Scilab 6.0-b1 did not yet include it. slint is a Scilab code
checker.<br>
<br>
The Scilab community has not been involved to design it</font><font
face="Arial">, i mean beyond the CNES (as likely the customer
having</font><font face="Arial"> ordered for it). S/E is planning
to include slint into Scilab.<br>
<br>
Due to this possible inclusion in Scilab, that would make slint()
distributed to all users, i would like to make some remarks and
suggestions about this module, as i would like a lot reading other
comments from other users and developers about this module. <br>
Below i will focus on some aspects about slint() "interfaces"
(prototypes, data formats), since interfaces turn rather locked
after the first publication (wherever it is published, in Scilab
or on ATOMS). I have not made deep tests about the current parser
/ slint engine, and beyond some unit tests about a subset of split
code checks, i did not see any code sample gathering all features
presently checked by slint().<br>
</font>
<ol>
<li><font face="Arial"><b>In Scilab, or a complementary module</b>
?<br>
slint is not specific to any type or area of applications,
since it is dedicated to Scilab code "qualification", whatever
is the purpose of the code.<br>
However, it is a rather specific development tool, clearly
oriented to developers working on "high standards". It is more
about computing sciences than for engineering and prototyping.<br>
In its "<i>Scilab development</i>" category, ATOMS already
proposes other development-specific modules -- that are tagged
<i>Complementary</i>, such as <i>Scibench</i>, or <i>assert</i>.
<i>assert</i> in now included in Scilab, since it is used by
almost all non-regression tests that are as well included
(whether they aren't unchecked in Scilab's installer). <i>slint</i>
is somewhat another module for benchmarking, but applied to
the code style and syntax, instead of to the code speed. IMO,
it would not be shocking to put it only on ATOMS as a
complementary module, and/or to leave the user decide through
Scilab's installer if he/she wants to install it by default.<br>
</font><br>
</li>
<li><font face="Arial"><b>slint's name: slint?</b><br>
I am not convinced by this module name and (unique) function
name. It does not clearly tell what it does. Should we guess
that "s" stand for <i>S</i>cilab (if so, is it worthwhile to
remind it?), and lint for code-washing residues?<br>
Here are some suggestions: codeCheck(), codeDiagn(),
codeQualify(), codeValidate(), </font><font face="Arial">codeWash()...
codeCheck() or codecheck() would look the most appropriate to
me. By the way, slint's pages talk about <i>checking</i>
rules.<br>
<br>
</font></li>
<li><font face="Arial"><b>Syntaxes</b><br>
The current slint() help page shows the following:</font><br>
<font face="Arial"> </font>
<div class="refsynopsisdiv">
<h3 class="title"> <font color="#3333ff"><small>Calling
Sequence </small></font></h3>
<font color="#3333ff"><small> </small></font>
<div class="synopsis"><font color="#3333ff"><small> </small></font>
<pre><font color="#3333ff"><small><span class="functionid">slint</span><span class="default">(files [, conf, out])</span>
<span class="functionid">slint</span><span class="default">(files [, out])</span>
<span class="default">out = </span><span class="functionid">slint</span><span class="default">(files [, conf], print)</span></small></font></pre>
<font color="#3333ff"><small> </small></font></div>
<font color="#3333ff"><small> </small></font></div>
<font color="#3333ff"><small> </small></font>
<div class="refsection"><font color="#3333ff"><small> </small></font>
<h3 class="title"><font color="#3333ff"><small> Arguments </small></font></h3>
<font color="#3333ff"><small> </small></font>
<dl>
<dt><font color="#3333ff"><small> <span class="term">files</span>
</small></font></dt>
<dd><font color="#3333ff"><small>a matrix of strings, the
.sci files or the directories to analyze. </small></font></dd>
<dt><font color="#3333ff"><small> <span class="term">conf</span>
</small></font></dt>
<dd><font color="#3333ff"><small>a scalar string, the name
of the configuration file (by default it's
SCI/modules/slint/etc/slint.xml). </small></font></dd>
<dt><font color="#3333ff"><small> <span class="term">out</span>
</small></font></dt>
<dd><font color="#3333ff"><small>a scalar string, the name
of the output file. </small></font></dd>
<dt><font color="#3333ff"><small> <span class="term">print</span>
</small></font></dt>
<dd><font color="#3333ff"><small>a scalar boolean, if true
the result is printed else the result is a struct. </small></font></dd>
<dt><font color="#3333ff"><small> <span class="term">out</span>
</small></font></dt>
<dd><font color="#3333ff"><small>a struct (if print is
false). </small></font></dd>
</dl>
<font color="#3333ff"><small> </small></font></div>
<font color="#3333ff"><small> </small></font>
<div class="refsection"><font color="#3333ff"><small> </small></font>
<h3 class="title"><font color="#3333ff"><small> Description </small></font></h3>
<font color="#3333ff"><small>slint has been written to check
the "quality" of the Scilab's code according to
configurable rules. </small></font><br>
<div class="refsection">
<h3 class="title"> <font color="#3333ff"><small>Examples </small></font></h3>
<font color="#3333ff"><small> </small></font>
<div class="programlisting">
<pre class="scilabcode"><font color="#3333ff"><small><span class="scilabid">slint</span><span class="scilabopenclose">(</span><span class="scilabstring">"SCI/modules/elementary_functions/macros/atanm.sci"</span><span class="scilabopenclose">)</span><span class="scilabdefault">;</span></small></font></pre>
</div>
<font color="#3333ff"><small> </small></font></div>
<font color="#3333ff"><small> </small></font><br>
<b>Remarks</b>:</div>
</li>
<ul>
<li>slint() application to .sce scripts is not documented. Is
this usage possible? Is it already runnable?<br>
<br>
</li>
<li>slint() application to compiled Scilab functions is not
possible or documented. Yet, as for profiling tools, this kind
of input would be handy.<br>
<br>
</li>
<li>print = %f should rather be the default. %T is currently the
default. For boolean variables, for my own i try to use or
document variables names with a final "?" => "print?", to
remind that they are boolean. BTW, it is here "disp?" rather
than "print?". Just a matter of documentation.<br>
<br>
</li>
<li>The <i>out</i> structure of results <br>
</li>
<ul>
<li>can be as well an input parameter. This usage is quite
unexpected and is not explained.<br>
<br>
</li>
<li>Fields and organization of the structure is not
documented. But running the example provides some insight to
it:<br>
<tt><small>-->
slint("SCI/modules/elementary_functions/macros/atanm.sci");<br>
In SCI\modules\elementary_functions\macros\atanm.sci:<br>
At l. 0, c. 0: 00015: Maximum line length exceeded at
lines: 24, 28, 35.<br>
At l. 24, c. 15: 00029: A function argument must be
preceded by a single space.<br>
At l. 24, c. 15: 00029: A function argument must be
preceded by a single space.<br>
At l. 27, c. 8: 00028: Operator <> should be
surrounded by single spaces.<br>
At l. 28, c. 15: 00029: A function argument must be
preceded by a single space.<br>
At l. 28, c. 15: 00029: A function argument must be
preceded by a single space.<br>
At l. 31, c. 8: 00028: Operator == should be
surrounded by single spaces.<br>
...<br>
At l. 45, c. 7: 00028: Operator / should be surrounded
by single spaces.<br>
At l. 45, c. 7: 00028: Operator * should be surrounded
by single spaces.<br>
At l. 45, c. 7: 00033: Expression is not bracketed.<br>
At l. 47, c. 12: 00028: Operator == should be
surrounded by single spaces.<br>
At l. 47, c. 29: 00028: Operator = should be
surrounded by single spaces.<br>
Module developed with the contribution of CNES.<br>
<br>
</small></tt><small><big>And by grabbing the output in a
variable and canceling the printing-in-console:<br>
</big></small><tt><small><br>
--> results =
slint("SCI/modules/elementary_functions/macros/atanm.sci",
%f)<br>
results = <br>
file: [1x1 string]<br>
info: [1x1 struct]<br>
<br>
--> results.file<br>
ans =<br>
SCI\modules\elementary_functions\macros\atanm.sci<br>
<br>
--> results.info<br>
ans =<br>
00029: [8x1 struct]<br>
00015: [1x1 struct]<br>
00028: [17x1 struct]<br>
00009: [1x1 struct]<br>
00033: [3x1 struct]<br>
<br>
--> results.info("00033").loc<br>
ans =<br>
ans(1)<br>
39. 22.<br>
39. 34.<br>
<br>
ans(2)<br>
39. 22.<br>
39. 26.<br>
<br>
ans(3)<br>
45. 7. <br>
45. 28.<br>
<br>
--> results.info("00033").msg<br>
ans =<br>
ans(1)<br>
Expression is not bracketed.<br>
<br>
ans(2)<br>
Expression is not bracketed.<br>
<br>
ans(3)<br>
Expression is not bracketed.<br>
<br>
</small></tt><b>Comments and suggestions</b>:</li>
<ol>
<li>imo, this structure for the results looks uselessly
complicated, and finally inefficient. It makes choosing
how to filter and view results very difficult:<br>
</li>
<ul>
<li><font color="#999999">the "info" field could be
renamed "results". Its contents are for example not
"contextual or configuration infos". To be clearer,
they are results.</font></li>
<font color="#999999"> </font>
<li><font color="#999999">this .results field could rather
be a simple list, with as many components as there are
analyzed files. </font><br>
</li>
<li>Each .result(i) component could rather be a matrix of
text. If a file has fully passed checkings, its results
are [].<br>
The matrix would have the following columns: </li>
<ul>
<li>line number (ideally with leading 0 to make
lexicographical and numerical orders matching)</li>
<li>column number (idem)<br>
</li>
<li>checker id</li>
<li>message</li>
<li>file basename (with the file extension, but without
the path)</li>
<li>file id (# rank in the list of files), converted
into text <br>
<br>
</li>
</ul>
<li><b>Finally, wondering about all what is written
here-above, i think that removing the splitting
between .fileS and .results (.info) fields would even
be preferable. </b><br>
<b>A single matrix of text would be much simpler and
more efficient</b>. To do so, for each new file, its
full path shall be recorded in the results matrix, in
the <i>message</i> column, with the code-row=0,
code-colum=0, checker-id=00000, given file basename and
rank#.<br>
It would be much easier to filter and sort according to
any column or multicolumn sorting. Very easy to record
in a .csv file ; etc. Very easy to reimport, to compare
or merge with other files ; to make statistics with that
; etc. All things very hard to do with the current
structure.<br>
<br>
</li>
</ul>
<li>The present structure is so rigid and unhandy that it
prevents basic filtering operations (like for instance
relisting results (out of console) in the order of rows of
code in the file). <br>
By the way -- but this has no importance, since the
structure should rather be abandoned --,<br>
</li>
<ol>
<li><b>id of checkers</b> starting with a digit prevents
using the .dot field addressing. Why not prefixing them
with a letter (say "r" as "rule" or "c" as "criteria")?<br>
<br>
</li>
<li><b>.loc</b> field is a list. Yet, its components have
all the same types and sizes, in such a way that they
could rather be stored in rows of a matrix. This would
allow filtering operations with find().<br>
<br>
</li>
<li><b>.msg</b> field: same remark: a matrix of text would
be more handy.<br>
<br>
</li>
</ol>
</ol>
</ul>
<li><b>Checking rules look not to be categorized</b>. Yet, some
rules are "only" about the code style, some others about
deprecated or removed features, etc.<br>
Presently, it is not easy to filter results by type of "lint".
We must somewhat look at all lints or at none or at some
specific ids. For instance, if i want to use an external
module and before i want to assess its runnability, i won't
care about its code style (i am not the author, and i don't
want to spend time on the code style of an external module),
and i would wish to get and fix all deprecated or removed
features in a straightforward way. To do so, defining subsets
and tagging checkers in them would be handy.<br>
<br>
</li>
<li>Presently, slint() does not allow <br>
</li>
<ul>
<li>to <b>provide a </b><b>Scilab version against which the
Scilab code must be checked</b>. <br>
</li>
<li>to provide a subset of rules (or categories of rules) that
must be checked, instead of checking all defined rules.<br>
<br>
</li>
</ul>
</ul>
<li> <b>Documentation pages</b>.<br>
The 40 pages about checkers (checking criteria/rules), with for
most of them only half-a-line of description, and nothing else,
and nothing more expected, made me deeply wondering: which
reviewer has accepted that, and who has accepted to merge that?<br>
For instance, if we spam in the same way the help tree just by
splitting the <i>axes_properties</i> page in 40 distinct pages,
with one property per page, do we have a chance on review to be
accepted and merged?<br>
This way of doing is shocking.<br>
By the way, i have searched these 40 pages on GIT/master to
propose merging them (in a table, even more suitable than in a
variablelist), but i did not find them. Quite strange.</li>
</ol>
<p><br>
Hoping to read other comments soon.<br>
BR</p>
<p>Samuel Gougeon<br>
<br>
</p>
<ol>
</ol>
<p><br>
</p>
</body>
</html>