[erlang-questions] Rhetorical structure of code: Anyone interested in collaborating?

[Miles Fidelman]

Along the lines of "write the executive summary first."


On 5/4/16 2:42 PM, Éric Pailleau wrote:
>
> Hi,
> It is certainly unusual, but I almost always start by writing user 
> documentation,  before coding.
> There is some interests to do so.
> First, documentation exists at end of project because it exists at 
> beginning.
> Second, documentation describe simple things like you would need as a 
> user, and not complicated things as consequences of bad coding. Coding 
> is then driven by this goal, and generally simplify the code itself.
> Third, coders know the goal to achieve at start and do not loose time 
> in, finally, unneeded things.
> I really recommend to do this experience.
>
> "Envoyé depuis mon mobile " Eric
>
>
>
> ---- Grzegorz Junka a écrit ----
>
>
> > - I have said several times that we write code because it is quicker to
> > write it from scratch, than to discover code that does what we want, or
> > modify code that does almost what we want but not quite.
> >
>
> That's very true, but it applies all the way through. The more time has
> been invested into some code the more time it would be needed to write
> it from scratch. For example, I would prefer Elixir's convention of
> listing the object on which the operation is being performed as the
> first argument in library function calls over the OTP convention of
> listing it as the last argument. But I am not going to rewrite OTP
> libraries for that small inconvenience.
>
> Very often understanding an existing application and fixing issues is
> easier and quicker than writing a new one from scratch, especially if
> one only need to understand a specific or small part of it, and even
> more if the existing application supports plugins allowing to skip large
> parts of its code in custom modules.
>
> This should be a lesson for those who design applications and its
> interfaces, and in my opinion putting effort into designing the
> application properly is more important than documenting everything,
> because it's always a trade-off. Very often the documentation isn't
> there not because it's not needed, but because there was not enough
> resources to put it there in the first place.
>
> If the architecture is good then the documentation can always be added
> later. But if the architecture is not good, then no matter how much
> documentation is written, it will be quickly outdated by the constant
> and often fixes and patches to that architecture to make it working.
>
> Grzegorz
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED <mailto:erlang-questions@REDACTED>
> http://erlang.org/mailman/listinfo/erlang-questions
>
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions

-- 
In theory, there is no difference between theory and practice.
In practice, there is.  .... Yogi Berra

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160504/506076c7/attachment.htm>