Skip to content

Commit

Permalink
Add a new article about naming convention.
Browse files Browse the repository at this point in the history
This article explain what was discussed in the RFC : hoaproject/Central#54
  • Loading branch information
shulard committed Jun 20, 2017
1 parent 316b828 commit 11d92df
Showing 1 changed file with 92 additions and 0 deletions.
92 changes: 92 additions & 0 deletions Source/Posts/2017/07-Introduce-data-conversion-naming.xyl
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
<?xml version="1.0" encoding="utf-8"?>
<?xyl-overlay href="hoa://Application/Overlays/Article.xyl"?>
<?xyl-meta name="title" value="Introduce data conversion naming"?>
<?xyl-meta name="date" value="2017-07-01T07:54:50+02:00"?>

<overlay xmlns="http://hoa-project.net/xyl/xylophone">
<article id="main">
<p>
For 2017, we <a href="http://discourse.hoa-project.net/t/roadmap-to-2017-a-draft/235">defined
a roadmap</a> composed of Request For Comments (RFC) that are discussed
and implemented. One if these RFC is about
<a href="https://github.com/hoaproject/Central/issues/54">naming convention
and simplification</a>.
</p>
<p>
So far, we use this formalism: <code>getFoo()</code> to name a method
that returns the value <code>foo</code>. This can be a direct attribute, or a
computation. To get this data within another form, i.e. to convert this
data into another type, we don't have any formalism yet. For instance,
if <code>foo</code> is an array, and we would like to get it as a string,
we will probably name a method like <code>getFooAsString()</code> but this
is not deterministic.
</p>
<p>
Conversions can be expensive so the method prefix must be clear enough to
know operation cost directly inside the code.
</p>
<p>
We decided to introduce 3 method prefixes:
</p>
<table>
<thead>
<tr>
<th>Prefix</th>
<th>Cost</th>
<th>Consumes convertee</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>as</code></td>
<td>Free</td>
<td>No</td>
</tr>
<tr>
<td><code>to</code></td>
<td>Expensive</td>
<td>No</td>
</tr>
<tr>
<td><code>into</code></td>
<td>Variable</td>
<td>Probably</td>
</tr>
</tbody>
</table>
<p>
Example:
</p>
<ul>
<li>
Let's <code>$x</code> be a float. <code>asInteger()</code> will be
(almost) free.
</li>
<li>
Let's <code>$x</code> be an array. <code>toString()</code> will be
expensive because we have to iterate over the array, to allocate a
string, and to convert every pairs in the array as a string (like a
serializer).
</li>
<li>
Let's <code>$x</code> be an object. <code>intoArray()</code> will not be
that expensive, it might reference all attributes into an array, so
that's just one allocation.
</li>
</ul>
<p>
Conversions prefixed <code>as</code> and <code>into</code> typically
decrease abstraction, either exposing a view into the underlying
representation (<code>as</code>) or deconstructing data into its
underlying representation (<code>into</code>). Conversions prefixed
<code>to</code>, on the other hand, typically stay at the same level of
abstraction but do some work to change one representation into another.
</p>
<p>
This is not something we will use often, but it is important to have a
strict naming here. Based on this naming, the user will be able to choose
if the resulting data must be cached or not (for instance, all <code>to</code>
conversions are likely to be cached because they might be expensive).
</p>
</article>
</overlay>

0 comments on commit 11d92df

Please sign in to comment.