[erlang-questions] I need some advices for a framework I'm doing

[Ivan Carmenates Garcia]

Hi, 
Well the good news here is that I am making it together with a system a am also doing so, it any problems present I will notice they quickly and at the same time I will get feedbacks.

Regards documentation, that one of the thing a love more, so it will be plenty of it, with a lot of examples and explanations. Currently the code doc for any function and even examples of how to use them. i.e. this is a nice doc for one of the functions:

%% -------------------------------------------------------------------
%% @doc
%% Makes a query to a database using a 'DBSession'.
%% Returns a 'ResultData':
%% - 'ResultData' depends of 'result_format' Option.
%% - 'result_format' could be one of 'raw', 'proplist', 'map'.
%% - 'proplist' and 'map' result formats have the same
%%   'ResultData' struct:
%%     {ok, Data} when using 'select'.
%%     {ok, Count} when using 'update', 'insert', 'delete'.
%%     {ok, Count, Data} when using 'update', 'insert' with returning.
%% The only differences are:
%%   0 results:
%%       'map' -> no_data,
%%       'proplist' -> [],
%%   1 result:
%%       'map' -> a single map #{...},
%%       'proplist' -> a list of proplist [[...]], (template compatible)
%%   N results:
%%       'map' -> a list of maps [#{...}, ...],
%%       'proplist' -> a list of proplists  [[...], ...],
%% 'raw' by the other hand is 'Backend' dependent.
%% Example:
%%   {ok, #{id := Id}} = database_manager:query(DBSession,
%%                           Query, Params, [{result_format, map}]).
%% NOTE: 'map' is the default result format for 'query/3' function.
%% NOTE: All result format has its pros and cons, 'raw' is the fastest
%%       but uncomfortable to deal with, 'map' is the slowest but very
%%       easy to deal with. So this is the performance order from
%%       fastest to slowest 'raw' > 'proplist' > 'map'. 'proplist' can
%%       be used to return directly to a template.
%% @end
%% -------------------------------------------------------------------
-spec query(DBSession, Query, Params, Options) ->
    ResultData | {error, Reason} when
    DBSession :: db_session(),
    Query :: string() | bitstring(),
    Params :: [] | [any(), ...],
    Options :: proplists:proplist(),
    ResultData :: any(),
    Reason :: term().
query({Backend, Connection}, Query, Params, Options) ->
    %% executes query/4 in the current 'Backend'.
    Backend:query(Connection, Query, Params, Options).


Anyone have more suggestions I could use?, thanks in advantage.

Regards,
Ivan.


-----Original Message-----
From: Loïc Hoguin [mailto:essen@REDACTED] 
Sent: Monday, August 24, 2015 5:45 PM
To: Ivan Carmenates Garcia; erlang-questions@REDACTED
Subject: Re: [erlang-questions] I need some advices for a framework I'm doing

On 08/24/2015 10:20 PM, Ivan Carmenates Garcia wrote:
> Hi everyone, I am making a little framework for cowboy, but in general 
> what I need is some advices regards final looking, i.e.:

OK I am a bit lost on everything you explained so allow me to give some generic advice:

* Make it work
* Start making apps with it
* Notice everything inefficient in how you now write apps
* Update your framework
* Repeat

Practice makes perfect. Add a little of looking at how everyone else does things in the mix to get ideas; sometimes you will notice something is bad in your framework but have no idea how to make it better, that's why you need to look elsewhere. Sometimes the idea might come from a completely unrelated source.

A few more things:

* Keep it simple and explicit
* Focus on the use cases that benefit the majority of users
* Choose good, short names
* Write a user guide when things stabilize

On the last point, you want the guide separate from code entirely because this forces you to think about how you really use it rather than just documenting functions or modules one after another. Think of it like writing a book, except the only role of this book is to explain to others *what* they can do with your framework and *why* they will do things that way.

Once you get there, you should have a pretty good product, and you'll most likely have gotten a ton of users along the way.

Cheers,

--
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20150825/50ab15a9/attachment.htm>