7

I've just begun using a popular, well-documented graphics engine, and was given a month to create some small programs and get familiar with it.

The library is huge, and there are sections I haven't explored.

Due to a time-crunch, my tech-lead has asked me to start designing my software (sequence and class diagrams) even for the parts I haven't explored, just by looking at the documentation and figuring out the capabilities of those classes.

It's my understanding that designing software requires good knowledge of how something works. Does it make sense to create a design with only a vague understanding of how a class works, just by looking at the class's documentation? Shouldn't I be prototyping it with a small program, tweaking it here and there and understand how it behaves and THEN do the design for it?

Improve this question

5 Answers 5

Reset to default
7

Your own sequence and class diagrams probably do not depend that much on how the graphics engine behaves. During implementation, you will probably run into little quirks like 'I must call initFoo() before setupBar()' but those details most likely do not affect the design of your classes. Your tech-lead needs your design now, probably because other people depend on it, so I propose you create it.

Improve this answer
4
  • 1
    your answer makes sense, unless his graphics engine is not flexible enough, making some designs less feasible (think RoR)
    – João Portela
    Jan 25, 2012 at 10:58
  • 1
    Why creating a sequence or class diagram? I have never encountered a customer who is running their business off that. A spike on the other hand provides valuable insight in how to use a graphics engine. My preference therefore would clearly go away from nice pictures and towards running software. In my experience nothing beats running software. It's the only true measure of progress. I realize, though, that this heavily depends on the culture within which you work. You may have to make other choices.
    – Manfred
    Jan 25, 2012 at 11:13
  • João Portela: The flexibility (or lack thereof) should be assessable from the documentation; except when features actually do not work as documented. John: That's a question Nav has to discuss with the tech lead. I don't think that proposing to ignore the tech lead's orders makes a good answer.
    – user281377
    Jan 25, 2012 at 12:04
  • Correct, the tech-lead needs the design now because others depend on it. We're to get these docs ready so that a foreign team (we're maintaining the software they created) can review it and they're visiting our country in a week's time. They don't know the new graphics engine, so they won't really be able to review it, also given that a lot of the class and sequence diagrams are auto-generated in EA, and hence human-un-readable. TL's main objective appears to be to get us to do things quickly as there's a lot of slippage because of a team member who left the company.
    – Nav
    Jan 25, 2012 at 12:24
2

There is a risk: just because the engine is popular and well documented, that might not reflect reality. I did use one game engine recently that used a wiki to documentation how the engine worked. What you found was a mixture of old pages that didn't reflect the most recent version, current pages, and ones that were talking about not yet implemented parts.

If I had been asked to design the application, based on the documentation alone, we would have been promising things that would not be available for years.

Improve this answer
1
  • If the documentation is old and does not reflected the current version then its not engine in question was NOT well documented.
    – Ramhound
    Jan 25, 2012 at 15:41
2

It is important that you provide a design because some preliminary work needs to go into creating a project. I like ammoQ's answer as he puts it best.

I would just like to add however that in an ideal world we will have all the time to become experts in an unknown framework or library before we commit to designing a software around something that isn't yet 100% understood. We do not live in a perfect world however.

Every design document should have an Assumptions section that details every remaining unknown that we still have about aspects of the design. If for example the documentation for the library claims to have functionality A, but you were not able to figure that out yet in your prototype, then claim it as an Assumption and design accounting for it being true.

You may from time to time find that not all of your assumptions were correct, or that perhaps you missed a few. At this point you will need to revise your design and cite the failed assumption as a reason, as well as revise estimates going forward.

Improve this answer
1
  • +1; I like your idea with the Assumptions section, but I would only mention claims that are relatively likely not to be entirely true. For example, a framework that promises "cross browser compatibility" might make me write the assumption "xxx takes care of all cross-browser issues" in this section. On the other hand, the assumption "List.first() delivers the first item of a list as specified" is very unlikely not to hold, so I would omit it in the Assumptions section.
    – user281377
    Jan 25, 2012 at 14:02
1

The answer really depends...

If you want to design a highly maintainable software, in which you can yank out the graphics engine and put in a new one, then you can do a high-level design without getting into too much detail on how to use the graphics engine.

If you want to base your design on that of the graphics engine (high coupling), then you need to know its specifics up front.

Improve this answer
1
  • In this case, I'm actually trying to yank out a highly coupled graphics engine and replace it with a graphics engine which is to be 'yankable'. All in VC++.
    – Nav
    Jan 27, 2012 at 2:44
1

Shouldn't I be prototyping it with a small program, tweaking it here and there and understand how it behaves and THEN do the designing for it?

That depends on what you want to do

The answer is in how your company do things. I personally would choose the second (agile) approach.

By the way, your design shouldn't depend so much on a library's implementation.

Improve this answer
2
  • 6
    "Your design should depends only on requirements." - I don't fully agree. If you mean only a high level sketch, then yes. But design choices in general are obviously influenced by things other than the requirements (e.g. architecture, language(s) used, and yes, framework implementation).
    – Péter Török
    Jan 25, 2012 at 10:25
  • "if you want some sort of agile iterative and incremental development, then no you do not need a detailed understanding of how things work, because your design will be more flexible" - that's a non sequitur
    – quant_dev
    Jan 25, 2012 at 12:43

Your Answer

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

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