Defining the ground truth

[Tim Daly]

Is "the ground truth" your spec or your code?

Here is an interesting read:
http://shanecelis.github.io/2013/05/20/why-im-trying-literate-programming

Shane started with a co-worker, working from a spec, to create a program.
He eventually found that only he could make changes because only he
understood the code and the spec was out of date.

The last big project I worked on had 6 people for 6 years. The central
data structure eventually became complex. It had optimizations and
mountains of code that depended on them. When we tried to write a new
and "better" central algorithm it turned out that nobody knew all the
various substructures embedded in the main data structure so we
couldn't make the improvement. The person who "managed" the main data
structure had left the project, taking with him all the knowledge.
The program died.

Are you limiting our ability to collaborate because you don't communicate?
Do we have to read (and reverse engineer) your code before we can write?
Does your code "add, change, or extend" the spec with special cases?

Can you keep up with the whole team using reverse engineering?
Can you identify "the person" who holds it all together?
Is your whole project "dead code" if certain people leave?

If you want your code to live, communicate.
Write words for people who will maintain your code but you'll never meet.

Tim Daly
Knuth fanboi

[Chris Ford]

On every project I've ever worked on, specs were ephemera, falling out of date almost immediately despite occasional herculean efforts to keep them up-to-date.

Personally, the best answer I've found to the spec/code dilemma to be automated tests, as they evolve along with the code and fail if they're out of date.

It sounds also like the project you're talking about had a lot of good ol' fashioned technical debt. Code won't be readable if it's badly written - but neither will natural language.

Cheers,

Chris

--
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to
clojure+u...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups "Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email to clojure+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.