Sign in to follow this  
3dmodelerguy

Designing Code?

Recommended Posts

When you have a project in which you know you need to design some of the code (like classes, interfaces, methods/parameters, members, etc...) before you actually jump into your code editor to write it, what do you use to design the code? Do you use a UML tool, and if so what tool? Do you just write it out on a piece of paper or whiteboard? Do you never design your code and always just jump into the actually coding process? Do you do something else?

Share this post


Link to post
Share on other sites
I design on whiteboards for preference. If that's not available, flipchart pad and biros -- there's loads of space on a flipchart pad. A4 just runs out too fast.

Like Talroth, I've never really found a tool which helps more than gets in the way. When I'm done with the designing, I sometimes write up the microarchitectures neatly so they can be stored as part of the docs.

For that I use either something like Inkscape (which has a connector tool) or in my own notation which then gets turned into Graphviz input by a perl script, and that makes svg for storing in a wiki.


Share this post


Link to post
Share on other sites
We don't do that.

Remember the YAGNI principle.


Trying to "design" those items (classes/interfaces/methods/parameters) is a waste of time. Is it significant to your game if a function takes two parameters or three? Is it significant to your game if your class is named Foo rather than Bar? Doing this is a significant time sink. You spend time thinking about stuff that really isn't a problem. You spend time writing code you don't need. You spend time maintaining something you will never use. Spending your valuable time and effort on unnecessary items is wasteful.

If you were working on something like an operating system, or a programming language, or a broad externally-used library, then it would make sense to do quite a lot of interface design. In that case you would listen to your users and understand their preferred usage patterns. Only after you know how they will use it should you build your interface around it. But chances are good that you're not making one of those.




We have design documents that describe how the game is supposed to work from the user/designer perspective. We have documents for coding standards that cover coding style, naming conventions, hierarchy standards, and so on.

The designers and senior developers break those conecpts down to individual items that can be done in a week or two, although sometimes there are very large items that can't be broken down further. Again, this is logical implementation details, not the classes/interfaces/etc.

From there we use scrum planning to break up the big tasks into very small tasks that a single programmer can do in a few hours or days. Again, there are no formal code requirements, only tasks to meet the conditions of satisfaction that actually make our game.


However...

On a very rare occasion, we will have core engine components that need to be authored or redesigned. The functionality is researched and somebody is assigned to build a prototype framework. Once they build it up, the spend that much time again breaking it down and eliminating stuff. Then the senior people and anybody else who has an interest in it will work on it from within Visual Studio, on a projector. The implementer has already designed the abstract base classes, leaf classes, and interfaces. They will also have several examples of how the main features will be used by the other programmers.

The group then review it and make suggestions for necessary changes. The first thing we look for is items to cut, and prioritize the items we need. We know YAGNI, so we'd rather delay the work if we are not absolutely sure we will need it later. A full UI system can be broken down to a handful of essential functions and a very simple tree. The second thing we look for is examples of how we will actually use it. If it is hard to use then the design is bad.

Even in that review we aren't looking at the details of the members and parameters, only checking that the functionality we need is there and that the functions are intuitive and easy to use for the main functionality. Once their very first core features are in place people immediately begin using it. They give feedback as they use it and the code and development priorities are modified to reflect the actual need.

Share this post


Link to post
Share on other sites
I actually use my own tool, LucidChart (see sig). I actually decided to create it because it was so painful trying to work together with a team on a Visio flowchart to map out some complex processes.

I don't usually use UML or even attempt to draw out all the requirements of a project. I just whip up some flow charts to help visualize some of the more complex processes--like recently, the flow through a complex new billing system.

Share this post


Link to post
Share on other sites
For my own projects, I'll likely use either the VS Class Designer or some freeware like ArgoUML to lay down some designs for classes. Sometimes, I just create classes in VS and randomly throw bits of code in until I get a half-arsed inheritance setup going. For general points, I keep an A4 pad and a pen on my desk to scribble down rough thoughts on as I go along, and it also serves as a todo list for the following day as I can update it whenever I stop or whenever I go home from work, etc.

As for how it was done at the 16 week internship I worked in 2008... *shudder*. I would love to tell you, but can't because a) it'll chill you to the bone and b) it's so uniquely terrible that my former boss will spot it immediately as their practices, will likely join the dots and withdraw the glowing reference he's been giving me. Let's just stop at saying it was truly hideous and no design process at all would have been an improvement.

Quote:
Original post by Katie
I've never really found a tool which helps more than gets in the way


Me neither. I never quite understood Rational Rose which is horrendously expensive yet unbelievably clumsy and unintuitive.

Share this post


Link to post
Share on other sites
Quote:
Original post by ukdeveloper

Quote:
Original post by Katie
I've never really found a tool which helps more than gets in the way


Me neither. I never quite understood Rational Rose which is horrendously expensive yet unbelievably clumsy and unintuitive.


Henceforth we shall not mention Rational Rose, or for that matter, any of the Rational Toolset-- as even muttering the name "ClearCase" three times in succession may cause a random developer in the world to instantly suffer a fatal heart attack.

Share this post


Link to post
Share on other sites
Quote:
Original post by BeanDog
I actually use my own tool, LucidChart (see sig). I actually decided to create it because it was so painful trying to work together with a team on a Visio flowchart to map out some complex processes.

I don't usually use UML or even attempt to draw out all the requirements of a project. I just whip up some flow charts to help visualize some of the more complex processes--like recently, the flow through a complex new billing system.


Woah that's a nice tool. Why didn't I know about that a long time ago? It just needs straight lines with cornered bends and it would beat inkscape and dia with boatlengths

Share this post


Link to post
Share on other sites
Personally I use Unit Testing and TDD. I will sit down at my editor and say, "ok what does this class have to do." Write my unit tests. Then write the actual code till the unit tests pass. Once they pass I move on to the next piece. This helps to keep me from writing a lot of functionality that will not get used. After words if I find it is not up to my standards in ease of use I will re-factor. The unit tests will tell me if I broke anything in the process.

No UML, no use cases or the like just unit tests and a quick brain storm.

Share this post


Link to post
Share on other sites
Quote:
Original post by BeanDog
I actually use my own tool, LucidChart (see sig). I actually decided to create it because it was so painful trying to work together with a team on a Visio flowchart to map out some complex processes.

I don't usually use UML or even attempt to draw out all the requirements of a project. I just whip up some flow charts to help visualize some of the more complex processes--like recently, the flow through a complex new billing system.


Now THAT is an excellent piece of software. Reminds me of Google Documents ^^

As for the OP, personally I don't do much code designing. I find it mostly a waste of time. I do make a small design document about the project: what should it be, the goal, audience and some other formal stuff.

I _am_ a perfectionist though...sometimes I change names of classes three times so it perfectly fits the class' functionality...takes me a lot of Find&Replace actions. So yes, sometimes it's better to properly design the project, but for 80% of the code it's useless as you already have in mind what it should be.

Always work in modules, so you never lose track because of the complexity.
For the global project (inter-module connections) a UML scheme can be handy I guess, but I must admit I forgot what everything meant in such a scheme...=/

Share this post


Link to post
Share on other sites
I also tend to be a paper & pencil guy, although the whiteboard-and-post-its sounds like a good idea too.

Generally, I lay out high-level structures -- libraries, namespaces, and primary classes -- and begin implimentation by getting the basic loop in place, then build up from there towards an atomic, end-user goal like "draw the background", "draw the characters", "move/animate the player character" starting with the most basic. When I start a new class, I try to enumerate and stub-out the functionality I'll need for certain and do that at once; less-certain functionality will be stubbed out with a TODO comment.

I've been around for awhile, so I trust my instincts to guide me in the implimentation details, but I'm also rather aggressive with re-factoring -- once I can see that usability is going down the toilet, or that responsibilites are starting to be muddled, I'll refactor then and there.

I also practice literate programming (even though I also comment, and maintain those comments, religiously) and re-name things as I find a better notion to match it to, or as its responsibilities change. I quite litterally count a thesaurus (thesaurus.com, specifically) as one of my most valuable programming tools.

I also work pretty much alone as far as code goes, both personally and professionaly, so I can get away with far less "process" than even adding a single other person would tolerate.

Share this post


Link to post
Share on other sites
I'm a hobbyist developer, so I don't really work on any "huge" projects. As such, pen and paper and some occasional use of UML has served me fairly well. I usually spend a few minutes designing a subsystem before attempting to implement it. If it doesn't work out, too bad, I start over. Otherwise, I go through the code and try to trim down as much as I can, and make it simpler. This process is repeated until I'm satisfied with the result.

Share this post


Link to post
Share on other sites
Quote:
Original post by frob
We don't do that.



Quoted for emphasis.


We've discovered that messing around with "design tools" making pretty pictures chews up far more time than just writing the code and adjusting it as needed. Sure, it means we iterate interfaces a lot, but that's not an issue for us as we have no external clients expecting a stable API.

In most situations, as far as my experience has taught me, it's a waste to draw up high-level designs and then code against the design. Inevitably you will forget something, add something that wasn't needed, and so on. Some team members may not feel comfortable challenging the design, and so you are very likely to end up with subpar code simply because nobody wanted to rock the boat. Other team members may end up spending excessive amounts of time picking holes in the design and trying to convince everyone that they need fixing (full disclosure: I am guilty of this on a regular basis).

IMHO, if you're not bound to keeping a stabilized API, just sit down and write the code. Writing it first on paper/whiteboards/napkins isn't going to reveal things to you any faster than writing the actual code in your editor. Especially if you use test-driven practices this can accelerate things quite a bit.

Share this post


Link to post
Share on other sites
Quote:
Original post by frob
We don't do that.

Remember the YAGNI principle.


Trying to "design" those items (classes/interfaces/methods/parameters) is a waste of time. Is it significant to your game if a function takes two parameters or three? Is it significant to your game if your class is named Foo rather than Bar? Doing this is a significant time sink. You spend time thinking about stuff that really isn't a problem. You spend time writing code you don't need. You spend time maintaining something you will never use. Spending your valuable time and effort on unnecessary items is wasteful.


I thought I understood this principle, until I was working on a section of my main project and all of the various features I had in place, unit tested and all; with massive configure-ability, plug-in support, Reflection to make it dynamic in all sorts of ways. Seven classes in this namespace, design-patterned, clever, a few thousand lines of code in all.

I ran into trouble though, some performance issues. I knew the solutions, but the solutions required the data to be formatted in a way my system didn't allow for - I could continuously optimize tiny parts of an algorithm with major performance caveats, or I would have to rethink my algorithm. After all, if I couldn't get it performing fast enough, there'd be no way to render the video output in any sort of efficient way; it was looking like it would take a few days to render a frame - nobody is going to be that patient.

So I rethought the algorithm. Managed to come up with a simple, elegant solution that fit in one class of 116 lines of code, excluding the bulky pre-processing which was now handled by an unmanaged C++ class with inline assembly (for image-filtering). It's not as flexible as the way I had been doing it, but it's exponentially faster. The features I eliminated were kind of cool, but they weren't being used. Not by me - I was getting sufficiently good results without really *having* to use the massively configurable properties of the object. Having a couple plug-ins was cool, but really, I just wrote one plug-in for it and worked exclusively on that; apart from a couple dummy and 'experimental' plug-ins that were more or less trips down the rabbit hole that slowed me down anyway.

-On the notion of plug-ins, the major thing that I learned is that the problem has to be very well understood before deciding on an interface for such a thing. When you deal with having to constantly alter your interface things get hairy, and slow you down. Probably better not to build this feature in from the start, but rather wait until there's a section of the program you want to become plug-in enabled and add plug-in support at that point.

So I hope that I have now learned the lesson a bit deeper. I've done it enough times now to know better, anyway!



Share this post


Link to post
Share on other sites
Mental modeling for relatively small bits of code (<5k lines or so). The daily commute and shower provide good time for that. Prototyping for things that are still fuzzy or unknown. I just make sure to spend enough time to have a good idea about what I want to do before I do it.

Whiteboards are the best way for larger programs, or communicating non-trivial/non-obvious designs with team members.

Share this post


Link to post
Share on other sites
Quote:
Original post by JSoftware
Woah that's a nice tool. Why didn't I know about that a long time ago? It just needs straight lines with cornered bends and it would beat inkscape and dia with boatlengths

Select some (or all) lines, open up the Properties panel (in the upper-right corner), and find the button to change them to elbowed corners. In the Document section of the Properties panel, you can also make defaults for those kinds of styles for the whole document.

Thanks for the good review :-) Sometimes I wonder if anyone else likes it as much as I do.

Share this post


Link to post
Share on other sites
One of my dreams is to design a program that gives the intuitiveness of pen/paper/whiteboard while gaining the flexibility of being in computer memory. Until then, I'm sticking with paper.

I like to use UML as a doodling tool, so I can design things visually. On a number of occasions I have filled a few pages of one of my notebooks with UML doodles, todo lists, sample code, etcetera. I like to have things planned before I go into them, or at least have a solid base from which to improvise, so I've thought a lot about how to make it easier.

Instead of note cards, it can be useful to use small slips of paper. They can be written on a large sheet and cut apart as needed. When the relationships between a group of them are fixed, I re-draw them on a larger slip with neater formatting, and paperclip the originals to the back. I recently did a fairly complete dependency map of my project this way. Or rather, I started with that, and drew it outright on paper when I had a feel for it. The biggest problem is that it was hard to describe the relationships between them without a drawable background. I used position and my imagination until I wrote it all down together.

I should probably find somewhere I can throw up a big whiteboard and draw stuff between sticky notes. Until I can do it on a computer, this sort of approach would probably provide the flexibility I want while still allowing me to dynamically show the relationships. I figure I need to be familiar with doing this stuff in real life before I can capture it in an application.

If nothing else, these sorts of software tools are useful for creating documentation after the fact.

Share this post


Link to post
Share on other sites
I don't design my code much, and I rarely use anything else than pen and paper, but sometimes I've found useful to write down at least a few core points (main classes, interfaces or use cases). This is also useful when you want to document your code or in collaborative scenarios.

Trying to write a full UML specification is a waste of time in most cases IMHO.

Share this post


Link to post
Share on other sites
I have always been a fan of StarUML, its a free piece of software that can do everything commonly found in a UML book; State, flow, sequence and class diagrams.

I never really used to design anything but then as my programming skill improved and my programs got larger I found I was missing things out or not programming things efficiently. StarUML is a graphical representation of code so made larger projects more manageable. I have a shocking memory so i could be working with one area of code for a bit then loose track of what todo next; the software just acts as a memory map for me. Another neat little trick with this tool is, if you have designed your system correctly it will actually write the barebone code for you freeing up a few tedious hours linking files and making sure relationships are correct.

Share this post


Link to post
Share on other sites
Quote:
Original post by BeanDog
Quote:
Original post by JSoftware
Woah that's a nice tool. Why didn't I know about that a long time ago? It just needs straight lines with cornered bends and it would beat inkscape and dia with boatlengths

Select some (or all) lines, open up the Properties panel (in the upper-right corner), and find the button to change them to elbowed corners. In the Document section of the Properties panel, you can also make defaults for those kinds of styles for the whole document.

Thanks for the good review :-) Sometimes I wonder if anyone else likes it as much as I do.


I am seriously impressed and I'm going to recommend it to everyone in my office today.

Share this post


Link to post
Share on other sites
Quote:
Original post by jjd
Quote:
Original post by BeanDog
Quote:
Original post by JSoftware
Woah that's a nice tool. Why didn't I know about that a long time ago? It just needs straight lines with cornered bends and it would beat inkscape and dia with boatlengths

Select some (or all) lines, open up the Properties panel (in the upper-right corner), and find the button to change them to elbowed corners. In the Document section of the Properties panel, you can also make defaults for those kinds of styles for the whole document.

Thanks for the good review :-) Sometimes I wonder if anyone else likes it as much as I do.


I am seriously impressed and I'm going to recommend it to everyone in my office today.


Seconded! (or thirded, or whatever).

The next time I need a flowchart tool, I'll turn to LucidChart.

Share this post


Link to post
Share on other sites
As the requirements of my project are not known in advance, I use a TODO list for my 'design'. It simply contains all the general features that are planed or currently broken, usually with some priority indicator.

When I start to work on a TODO, I loosely follow the following format:


TODO: feature [priority]

random thought on the subject
...
...
...

detailed feature requirements
...
...
...

solutions

solution 1: (changes/use/pros/cons)
...
...
solution 2: (changes/use/pros/cons)
...
...
...

final choice
...



It is not very fancy or anything, but it works for me. This way, the design document can be used later on to re-evaluate earlier design decisions. This is useful when refactoring code.

Dietger

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

Sign in to follow this