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

Grzegorz Junka <>
Wed May 4 21:08:17 CEST 2016


This is called Documentation Driven Development:

http://thinkingphp.org/spliceit/docs/0.1_alpha/pages/ddd_info.html
http://stackoverflow.com/questions/588760/documentation-driven-design-your-experiences
https://gist.github.com/zsup/9434452

This works as long as the documentation isn't over-specific. Otherwise 
it turns into a waterfall model of development.

Grzegorz


On 04/05/2016 18:42, É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
>  <mailto:>
> http://erlang.org/mailman/listinfo/erlang-questions

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160504/4b97f0ba/attachment.html>


More information about the erlang-questions mailing list