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?

  • 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!
    – Erik Eidt
    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...
    – YSharp
    Commented Oct 1, 2016 at 4:26
  • Is it translated from another language?
    – rwong
    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?
    – Doc Brown
    Commented Oct 1, 2016 at 8:33

3 Answers 3


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.

  • 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

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.

  • 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.
    – Doc Brown
    Commented Oct 1, 2016 at 8:27

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.