Add a new article about naming convention.

This article explain what was discussed in the RFC : hoaproject/Central#54

Author: shulard

Source/Posts/2017/07-Introduce-data-conversion-naming.xyl

@@ -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>