From e3039f2ff8c3e8a50e7bf9c4749d6b41e72b6065 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20HULARD?= Date: Sat, 17 Jun 2017 23:48:48 +0200 Subject: [PATCH] Add a new article about naming convention. This article explain what was discussed in the RFC : https://github.com/hoaproject/Central/issues/54 --- .../07-Introduce-data-conversion-naming.xyl | 110 ++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 Source/Posts/2017/07-Introduce-data-conversion-naming.xyl diff --git a/Source/Posts/2017/07-Introduce-data-conversion-naming.xyl b/Source/Posts/2017/07-Introduce-data-conversion-naming.xyl new file mode 100644 index 0000000..d380d02 --- /dev/null +++ b/Source/Posts/2017/07-Introduce-data-conversion-naming.xyl @@ -0,0 +1,110 @@ + + + + + + +
+

+ For 2017, we defined + a roadmap composed of Request For Comments (RFC) that are discussed + and implemented. One if these RFC is about + naming convention + and simplification. +

+

+ So far, we use this formalism: getFoo() to name a method + that returns the value foo. 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 foo is an array, and we would like to get it as a string, + we will probably name a method like getFooAsString() but this + is not deterministic. +

+

Property access

+

+ Initially we decided to remove the get prefix from getters + methods because it's not mandatory to understand the code. Also in many + languages this prefix have been drop/is not present so we can ask if it's + still relevant. +

+

+ After receiving some community + feedbacks it seems that this prefix is too present in the PHP world. + Removing it will make code more complex to read and understand for PHP + developers. +

+

+ We don't want to hurt Hoa projects adoption so we prefer + staying with the get prefix at the moment. +

+

Conversions

+

+ Conversions can be expensive so the method prefix must be clear enough to + know operation cost directly inside the code. +

+

+ We decided to introduce 3 method prefixes: +

+ + + + + + + + + + + + + + + + + + + + + + + + + +
PrefixCostConsumes convertee
asFreeNo
toExpensiveNo
intoVariableProbably
+

+ Example: +

+
    +
  • + Let's $x be a float. asInteger() will be + (almost) free. +
    • +
  • + Let's $x be an array. toString() 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). +
    • +
  • + Let's $x be an object. intoArray() will not be + that expensive, it might reference all attributes into an array, so + that's just one allocation. +
    • +
+

+ Conversions prefixed as and into typically + decrease abstraction, either exposing a view into the underlying + representation (as) or deconstructing data into its + underlying representation (into). Conversions prefixed + to, on the other hand, typically stay at the same level of + abstraction, but do some work to change one representation into another. +

+

+ 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 to + conversions are likely to be cached because they might be expensive). +

+
+