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

[Grzegorz Junka]

Excuses, excuses, ... :-)


On 04/05/2016 21:42, Éric Pailleau wrote:
>
> Yes. I do not pretend invent something there.
> However I do not do test driven dev after documentation.  looks better 
> for the team to start coding with a fresh idea of what to do.
> Tests can limit code inventiveness sometimes.
> Postone coding start is also stressing due to short delay. I prefere 
> to reduce time to do tests, but deliver in time the project, as far 
> those tests are added during life of programs, while bug fixing. This 
> justify also maintenance costs ;-)...
>
> "Envoyé depuis mon mobile " Eric
>
>
>
> ---- Grzegorz Junka a écrit ----
>
> 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
>> erlang-questions@REDACTED <mailto:erlang-questions@REDACTED>
>> http://erlang.org/mailman/listinfo/erlang-questions
>

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