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.
7
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)
7
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?
-
Of the implementation they want you to deliver?
-
Or of the hypothetical unit test of this implementation?
This is a very important distinction.
-
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.
-
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
2: Write a step definition in Ruby
3: Run and watch it fail (TBC)
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.
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.
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.