2

I'm a developer in the IT department of a large oil company. I received a spec document, basically in plain English, about business rules that need to be implemented in a new application. The rules are really difficult to translate into code, since I don't know all of the inner workings of the business.

Is it acceptable to ask management (the people who gave me the spec) for the rules in more of a pseudo code fashion or would I be looked at as if I had two heads?

"Management" in this case refers to guys who were once developers, but now have more of a management role here in IT.

closed as too broad by user40980, GlenH7, gnat, jwenting, Kilian Foth Oct 6 '14 at 11:10

Please edit the question to limit it to a specific problem with enough detail to identify an adequate answer. Avoid asking multiple distinct questions at once. See the How to Ask page for help clarifying this question. If this question can be reworded to fit the rules in the help center, please edit the question.

  • Most likely, management will now know what pseudo code is or how to write it. – DFord Oct 1 '14 at 19:36
  • 8
    Unless management consists of good programmers promoted to management, and puts serious effort into it, any pseudo code they'll write will be as informal and high-level as the spec you have. And even then, pseudo code leaves a lot of room for ambiguity since it's usually just plain English with idiosyncratic formatting. If the problem is that you can't comprehend the spec as given, then transcribing the spec into a different format won't fix that problem. – user7043 Oct 1 '14 at 19:36
  • @delnan Sorry, forgot to mention... "Management" in this case refers to guys who were once developers, but now have more of a management role here in IT. And I see what you're saying about the ambiguity, but I know these rules would be easier to code around if they were laid out in more of a "structured" "pseudo" way... – FastTrack Oct 1 '14 at 19:40
  • 1
    Psuedocode is real code written in a language that someone invents on the spot and has no spec nor implementation. A non-coder can't write pseudocode any more than they could write real code, and if the person is capable of coding, you might as well ask for code written in a real language. – Doval Oct 1 '14 at 20:17
  • 3
    Not really answering the question but I sometimes find that when business requirements are not clear because the developer is new to an industry or business then sometimes a glossary section will help that defines terms, abbreviations and gives cliff notes for complicated processes that can help provide context. Many times I am surprised how much this alone helps me understand complicated requirements. – maple_shaft Oct 2 '14 at 0:12
8

Don't ask for pseudocode. If your superiors thought you needed that, they would have provided it already.

Here's what you should do instead:

Make your requirements testable

If it's not testable, it's not a requirement; it's a feature or wish.

More specifically, each individual requirement should be SMART:

  • Specific
  • Measurable
  • Assignable
  • Realistic
  • Timely

Gather your requirements in such a way that they are specific enough to write code against, measurable enough that you and the customer can agree on a criteria for declaring success, assignable to someone who can do the work, realistic enough to be achievable, and timely (you can estimate time of completion and set due dates).

Further Reading
Mastering the Requirements Process: Getting Requirements Right (3rd Edition)

  • 2
    How does this really answer the question? It addresses the problem the user is facing but doesn't even pay credence to the actual question. Great answer, wrong question. – maple_shaft Oct 1 '14 at 20:07
  • 2
    @maple_shaft: No argument there. Is your assertion that I should simply answer the wrong question with "No," thereby providing no useful guidance? – Robert Harvey Oct 1 '14 at 20:09
  • 2
    @maple_shaft: I have edited the answer to conform to your specifications. – Robert Harvey Oct 1 '14 at 20:14
  • That is perfect. I guess all it takes is a simple sentence. – maple_shaft Oct 2 '14 at 0:08
  • 1
    Even after exhausting every other possible way of providing specs, managers aren't going to assume the developers need pseudo code, but instead need a new developer. – JeffO Oct 2 '14 at 2:46
3

Asking for pseudocode, in my opinion, stems out of frustration that requirements are ambiguous and not clear enough.

I agree with Robert Harvey that properly written requirements would - should - nullify the need of having pseudocode at hand.

Writing pseudocode could be sort of a practical exercise for the management to make them realize how unprecise they have been.

Maybe a great exercise, but we are not in a position to teach them, and it smells of homework as punishment to me ("I will not be giving ambiguous guidelines, I will not be giving..."). Writing pseudocode enforces precision, but at the cost of imposing certain formality.

What pseudocode would that be, anyway?

  1. Of the implementation they want you to deliver?

  2. Or of the hypothetical unit test of this implementation?

This is a very important distinction.

  1. This isn't really their job. They have no business in designing, or even knowing what's inside the blackbox, as long as the box does the trick. The same business logic could have very different algorithmic representations and it is up to the programmer to pick the one they like.

  2. I agree! Now you can write your implementation any way you seem fit, as long as it passes their test. Like TDD / BDD.

So now we're in the ballpark.

Because a properly written test suite reads like a good spec.

In fact, some frameworks really blur the distinction between specs and a test. Take a look at Cucumber, for instance (mind you, I am in no way affiliated with the product).

1: Describe behaviour in plain text

1: Describe behaviour in plain text

2: Write a step definition in Ruby

2: Write a step definition in Ruby

3: Run and watch it fail (TBC)

3: Run and watch it fail

  • 1
    +1 for suggesting behavior driven development. It sounds like the OP has some requirements that need some clarification, and something like Cucumber (or SpecFlow for you .NET folks) is a great way to both capture requirements AND make them testable. – Greg Burghardt Oct 2 '14 at 12:33
1

The essence of delivering products for customers is figuring out the communication process. Often the specifics are not initially clear and you'll have to move things in that direction. You will need to ask every question necessary until you understand the business process as it relates to your use case. Often this means you speak with an expert (usually a business analyst).

If you cannot be made to understand the specifics of the process you have little hope of writing proper code. Ultimately, your code should clearly articulate the process. In other words, write the code so that it demonstrates and understanding of what is supposed to happen. Normally, you want to use named variables to express the transitions from a starting state to a final state. Most processes are state machines of one form or another whether or not state machine is explicit in the code.

0

If you think it will help, yes, ask them for pseudo-code. Or, perhaps, more specific lower level descriptions of processes. Or a flow chart, even. If they are managers with a vested interest in your successfully finishing a project, why would they have a problem with the request?

If, though, you find that you need pseudo-code often, then there is clearly a communication issue between you and them. Either they are not being clear enough, and/or you are not very good at converting requests into code.

0

You have received tangled requirements, with business logic not entirely clear, and contexts still very vague. The problem is, that asking for "pseudo-code" will go half-way at most, without too much love, and then even hamper you in development; by half understood or not well tought out decisions. It will probably backfire even.

Make a story-board from it, part of the code design, and try to bring concrete details to bear. Structured little scenes, stories. Communicate that you are doing just that, and after a while communicate with the people on the material.

Best in document form, with depicted screens. Now documentation should not have much overhead, but my ideal would be a format like docbookx, that is versionable, conserves diagrams separately. But it should not take extra time and mind power, so go for docx / odt otherwise. Unzippable and then versionable.

If you then can bring structure in the whole, you have done half of the implementation. You know what's in it. You should be able to get feedback on most of the issues. Priorization for instance.

During implementation, you can give an overview of the work done.

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