3

I'm tasked with implementing a spec for a simple simulated shopping system. The spec however uses strange abreviations everywhere (it has a 2 page long table of nonsense abreviations). For example the contains lines like this:

Each potential VG has a AL of VGI's.

When replacing the abreviations using the abreviations table we get something that isn't much better:

Each potential value generator has an acquisition list of value generating items.

Through much digging and translating I decipher this to:

Each customer has a shopping cart containing a set of products.

This could be implemented in 2 ways:

class VG { private List<VGI> AL {get;} = new List<VGI>(); } class ShoppingCart { private List<Product> Products {get;} = new List<Product>(); }

Is it okay for me to write the code in the readable version? This would make the code readable to future victims of this project, but it would totally disconnect the spec from the actual code?

Improve this question
5
  • 3
    Just fyi, these items you're presenting in the two options are not equivalent; if you are presenting the choices between two options you might want to present them on the same example. Also there is a third (or middle) option: class AcquisitionList { private List<ValueGeneratingItem> ... }. and FYI option (1) is pretty bad, but I've seen worse! Commented Oct 1, 2016 at 0:38
  • 4
    Is murdering the writer of the spec an option? Commented Oct 1, 2016 at 3:48
  • @whatsisname thanks for the smile :) Even that, I doubt it'd help the OP -- the evil spec would still be around, as a major PIA... Commented Oct 1, 2016 at 4:26
  • Is it translated from another language? Commented Oct 1, 2016 at 7:56
  • 1
    Wil you get credits from your boss or your client for tranlating the spec into a usable form first? Commented Oct 1, 2016 at 8:33

3 Answers 3

Reset to default
2

Each potential VG (value generator) has a AL (acquisition list) of VGI's (value generating items).

In plain English, this means that each customer has a shopping cart containing a set of products.

Improve this answer
1
  • 1
    An explanation for the downvote would be nice in this case, since my answer is fundamentally correct. Commented Oct 2, 2016 at 16:43
2

Implement the readable version, and generate (automatically, if possible) documentation relating your terms to the spec's terms. For bonus points, include the spec in the generated documentation. With luck, the spec could be maintained in parallel with the source code.

Improve this answer
1
  • Translating the spec into something readable first before one starts implementing is surely the correct way to go. However, I think it is over-optimistic to assume a cryptic spec can be automatically translated into a readable one. IMHO it is pretty likely this could result in an even more cryptic document. Commented Oct 1, 2016 at 8:27
1

What jose_castro_arnaud mentioned in his answer (linking the human readable and spec specific terms) is a form of Requirements Traceability, a basic software engineering concept. You can also write a Data Dictionary that links the terms as they are literally found in the spec with the terms that you have chosen to use in order to accomplish this or a similar function. The end result will be similar in any case - providing future maintainers with a way to match (1..1) terms in your code with terms in the spec.

Improve this answer

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.