Related
Standard way of working on new API (library, class, whatever) usually looks like this:
you think about what methods would API user need
you implement API that you suspect user will need
So basically you trying to guess what your API should look like. It very often leads to over engineering stuff, huge APIs that you think user will need and it is very possible that great part of your code won't be used at all.
Some time ago, maybe few years even, I read some article that promoted writing client code first. I don't remember where I found it but author pointed out several advantages like better understanding how API will be used, what it should provide and what is basically obsolete. I think idea was that it goes along with SCRUM methodology and user stories but on implementation level.
Just out of curiosity for my latest private project I started not with actual API (some kind of toolkit library) but with client code that would use this API. Of course my code is all in red because classes, methods and properties does not exist and I can forget about help from intellisense but what I noticed is that after few days of coding my application "has" all basic functionalities and my library API "is" a lot smaller than I imagined when starting a project.
I don't say that if somebody took my library and started using it it wouldn't lack some features but I think it helped me to realize that my idea of this API was somewhat flawed because I usually try to cover all bases and provide methods "just in case". And sometimes it bites me badly because I made some stupid mistake in basic functions being more focused on code that somebody maybe would need.
So what I would like to ask you do you ever tried this approach when needed to create a new API and did it helped you? Is it some recognized technique that has a name?
So basically you're trying to guess what your API should look like.
And that's the biggest problem with designing anything this way: there should be no (well, minimal) guesswork in software design. Designing an API based on assumptions rather than actual information is dangerous, for several reasons:
It's directly counter to the principle of YAGNI: in order to get anything done, you have to assume what the user is going to need, with no information to back up those assumptions.
When you're done, and you finally get around to using your API, you'll invariably find that it sucks to use (poor user experience), because you weren't thinking about how the library is used (UX), you were thinking about what the library must do (features).
An API, by definition, is an interface for users (i.e., developers). Designing as anything else just makes for a bad design, without fail.
Writing sample code is like designing a GUI before writing the backend: a Good Thing. It forces you to think about user experience and practical effects of design decisions without getting bogged down in useless theorising and assumption.
And contrary to Gabriel's answer, this is not bottom-up design: it's top-down. Rather than design the concrete backend of your library and then force an abstract interface on top of it, you first design the interface and then worry about the implementation.
Generally speaking, the idea of designing the concrete first and abstracting from that afterwards is called bottom-up design. Test Driven Development uses similar principle to what you describe to support better design. Firstly you write a test, which is an use of code you are going to write afterwards. It is important to proceed stepwise, because you have to proove the API is implementable. IMportant part of each part is refactoring - this allows you design more concise API and reuse parts of your code.
How is a class diagram actually any different to just looking at the class definition with all the functions collapsed? I've been asked to write some and realized that this is all just .. read the source .. it has comments. What's the point of a class diagram, how is it different to even minorly commented definitions, and what makes a good class diagram better than others?
Edit: Yes, the source already exists, and did so long before the class diagrams.
Another edit: People have been talking about visual vs textual tastes. That's not the definition of class diagram I was given. It's still purely textual. The sample class diagram is a bunch of text, that resembles the source code with the function definitions cut. That's the reason that I asked. If it was a genuine diagram, I could understand.
If you have one or two classes, that does not make a diference.
If you have a complex object model, things change.
And, at least for me, is easy to look first at a diagram in order to look for what I want in stead of looking at a bunch of source files.
Also seeing the classes on a picture and their relations helps to understant the ideas of the project.
I'd rather have source. Given that, I can always reverse engineer it.
You have to ask what UML is for: it's just a communication device, a way to get your ideas across to other developers. If UML is helping, great. If it becomes another burden to maintain, prefer working code with good unit tests.
A good class diagram clearly shows each classes responsibilies and associations - at an appropriate level of abstraction.
Class diagrams are useful because they allow you to design at a higher level of granularity. Operations drawn on a white board are easier to change than source code. It also clearly shows associations through lines, rather than leafing through code.
They're helpful in that they are a segue from conceptual ideas to source code.
They let you say more with less.
If the source already exists, I guess it's the old adage, "A picture tells a thousand words".
For someone not familiar with the source, a diagram may help them to grok the overall design quicker then reading the source, no matter how well documented. Some people are more visual than others. Personally, I'd rather have the source.
Like many things, it's probably a matter of taste.
Edit:
I thought the definition of a diagram was that it is visual. However, if it's just a bunch of text, then the only point I can see is that it provides an overview of intent without the unnecessary implementation details.
The difference between looking at a diagram and the source is that you don't need to process as much data when looking at the diagram (a picture) than when reading the source (says thousand words).
In my experience I've found class diagrams to be very useful when I'm not familiar with the architecture of the software. But class diagrams don't replace the need for source code and proper documentation, they're just a communication and productivity tool that complement the methods I mentioned before. Their intent is to understand the software architecture. not to replace other documentations. How useful a class diagram is depends on its quality and the complexity of it and the source code.
Don't put too much detail into the diagrams. It makes them confusing. You'll want them to communicate relationships, not API and a list of methods.
They also help to see when and where to refactor code. Use class diagrams along with proper documentation and you'll be all set.
I'm not sure quite what definition you've been given for a Class Diagram - it sounds almost as though the example you've been shown has just one class on it. If so, I can understand why you think it's a bit ridiculous.
Class Diagrams are a way to show the relationships between classes - a good one can provide a lot of information about how your system works in one diagram that rewards careful study. It allows a developer unfamiliar with a subsystem to come up to speed quickly without getting mired in the implementation details.
Here's one simple one I found with a quick Google:
http://netbeans.org/images_www/articles/uml-class-diagram/Completed-Class-Diagram.gif
Some tools (Microsoft's Visual Studio is one) contain tools that allow you to draw a class diagram once and have it automatically kept up to date ("in synch") with the code. Very useful.
I've decided to get some experience working on some project this summer.
Due to local demand on market I would prefer to learn Java (Standard and Enterprise Editions).
But I can't even to conjecture what kind of project to do. Recently I had some ideas about C. With C I could to contribute to huge Linux projects. I don't mean that my work will be surely commited. I could get the code and practice with it. But C it's not right thing to get good job in my area. In case of JavaSE there is a chance to develop some desktop applications. But thinking about JavaEE I get stuck. I'll be very thankful for answers.
CodingBat.com will give you good core Java practice.
Project Euler is still the best for all around practice. You can use whatever language you'd like to solve the problems there.
For actual projects, I almost always start on something easy like a Twitter client. It gets you exposure to all the basics along with UI and network communication. You can work up from there. Just don't start with something so overwhelming that you can't figure it out and want to give up. That's not going to get you anywhere.
The best advice is: work on a project that you have personal interest in. Something based on your hobbies, maybe.
If that doesn't work, make a blogging / CMS engine. Or an online photo album. Or an eStore. The world doesn't really need another of any of these things, but it will give you some good practical experience with JavaEE.
Another benefit of "re-inventing the wheel" (for learning) is that you have probably already used systems like these described above, and you have a good idea of how it can work, and maybe you have your own ideas of how it could work better. That can make requirements much simpler, and also will give you a sort of benchmark so you can see how close you can come to building a tool like the "real" ones out there. And if yours is really great, well, maybe release it and see what happens. ;)
There are many Java-based projects on SourceForge. Tinker with one you find interesting.
I've implemented either a betting pool or a Baccarat game in almost every language I've
learned.
This type of software covers:
Dates and times, with calculations
Currency types and things that can be converted to and from currency.
A discrete set of rules that is easy to test
States, transition between states and multiple entities responsible for state transition
Multiple users with different views of the same model End conditions
Multiple player blackjack and poker would work also.
One caveat is that in my day job I work on financial systems and there is a huge overlap
between things to consider when writing a multiplayer game of chance and a trading system.
build an address book. the concept is simple, so you're not stuck on "what" to write. You can focus on learning your chosen language. You get experience in working with a database, java ( insert any language here), and UI design.
when you decide to learn another language you can create the same thing. Since the database has been created already, you can focus on the language itself.
the concept of inputting data, storing data, and retrieving data is central to a lot of applications.
Have a look around http://openhatch.org/ for a project that sounds interesting.
I'm using an MVC framework to develop a web site, I've to care about the design in the sense of look and feel (views) and the code (models, controllers).
I don't know what is the best way to proceed:
code and design iteratively by small chunks?
design first ?
you've got the point
I suggest you design first - it can be a rough design with a pencil/paper but it will give you an idea of what information should go on the page in what manner. This will help you with your views and controller logic. Dont' worry too much about colours at this point.
I always feel it is better to do things iteratively. Design a page or two, construct the model and controller relative to that page, and repeat for other pages.
Sometimes if you spend too long in your models and controllers and neglect your views, you'll end up doing way more or way less than what you need.
The 37 Signals (the source or Ruby on Rails and some really cool web apps) book Getting Real advocates working from the interface down. It gives you a better sense of how the site will be used before you do too much back end implementation.
Here is the specific chapter: From ideas to implementation.
PS: Read the whole book, it's brief and a really good overall philosophy for building things the way they should be build. And no I am not affiliated with them in any way.
One small, but very good tip I got, was to work out what kind of 'friendly' URL's you would like to see in your site. This in turn leads you to what routes your require, which in turn gives you an idea of the controllers and actions you will have to create.
It depends but there are several rules of thumb:
the bigger the project the more it benefits from the design first, design well approach.
if there's inter-dependence between the elements of the project - such as lots of foreign keys in the database - you are better off at the very least designing everything around those inter-dependencies, or you're gonna regret it later
MVC frameworks enforce some design decisions by their very nature, so use that to help you
beyond a certain size - say more than a week's work - it's an absolute necessity. Same goes if it's a team effort
In your particular case, since I'm not sure about the project size, I'd suggest having your schema designed ahead based on your needs, which will tell you about dependencies, and then do the iterative thing, starting with the dependencies.
If you have specific APIs you have in mind, it's a good idea to design around those as well
The beauty of MVC frameworks is it simply does not matter.
Obviously you'll need some vision to work to, but it's up to yourself. I'm a strong believer in iterative development. In this case you'd create a section of the site, views, models and so forth. Once that was working, move to the next section/feature of the site.
The both ways are OK but it would be better if you have a designed view (even a mock up) so you can know what data to get how to format it when you develop you model and controllers
My suggestion which will save you a lot of time and headache is start off with design.
You have two designs here. One is the UI (interface) design. All the visuals etc.
When you have a UI design you will know how to create your mark-up from the get go without having to do the work twice after you've completed a design.
The other is the software design. the MVC framework helps a lot with this but you also don't want to just start coding without having a plan. You'll find yourself back tracking a lot and recoding stuff you've already done that way.
An iterative approach is the way to go. I might suggest spending time on the model and getting it solidified first. Then, iterate through your controllers and views. This will help validate what you've done in the model, and bring up any glaring issues that need to be addressed sooner vs. later.
I, as most here would say design (at least to a extent) first.
I would wireframe interactions (these can, and should be be refined later) and, perhaps most important, (at least if it's a traditional web site you're working on) plan the architecture, map the structure of the site you're working on (the Information Architecture part). In order to get an overview of the site and know map out user paths through the content.
That's at least my 'modus operandi' for web sites if I'm working alone on them.
(I mostly work in a UX team so my professional workflow is more in the design part than production coding nowadays)
Understanding the Requirements
Database Design
User Interface Design
Business Logic Design
From my experience I would say you should always plan first. (I even plan my planning phase).
I assume you’re doing something like a GUI wired up via .aspx using the MVC model, maybe even the Entity Framework?
Web development like this can very easily get complicated once you start to build it up.
It is important that before you do anything you know exactly what it is that you are trying to do, this way you know when you are undershooting or overshooting your goals and whether or not the code you are writing actually fulfils the requirements.
There are many models which you can base your project development on, all of which loosely follow a sensible System Development Life Cycle in one way or another.
If you haven’t read up on the different development methodologies, here’s a site that will give you a good overview : http://www.itinfo.am/eng/software-development-methodologies/
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
One thing I struggle with is planning an application's architecture before writing any code.
I don't mean gathering requirements to narrow in on what the application needs to do, but rather effectively thinking about a good way to lay out the overall class, data and flow structures, and iterating those thoughts so that I have a credible plan of action in mind before even opening the IDE. At the moment it is all to easy to just open the IDE, create a blank project, start writing bits and bobs and let the design 'grow out' from there.
I gather UML is one way to do this but I have no experience with it so it seems kind of nebulous.
How do you plan an application's architecture before writing any code? If UML is the way to go, can you recommend a concise and practical introduction for a developer of smallish applications?
I appreciate your input.
I consider the following:
what the system is supposed to do, that is, what is the problem that the system is trying to solve
who is the customer and what are their wishes
what the system has to integrate with
are there any legacy aspects that need to be considered
what are the user interractions
etc...
Then I start looking at the system as a black box and:
what are the interactions that need to happen with that black box
what are the behaviours that need to happen inside the black box, i.e. what needs to happen to those interactions for the black box to exhibit the desired behaviour at a higher level, e.g. receive and process incoming messages from a reservation system, update a database etc.
Then this will start to give you a view of the system that consists of various internal black boxes, each of which can be broken down further in the same manner.
UML is very good to represent such behaviour. You can describe most systems just using two of the many components of UML, namely:
class diagrams, and
sequence diagrams.
You may need activity diagrams as well if there is any parallelism in the behaviour that needs to be described.
A good resource for learning UML is Martin Fowler's excellent book "UML Distilled" (Amazon link - sanitised for the script kiddie link nazis out there (-: ). This book gives you a quick look at the essential parts of each of the components of UML.
Oh. What I've described is pretty much Ivar Jacobson's approach. Jacobson is one of the Three Amigos of OO. In fact UML was initially developed by the other two persons that form the Three Amigos, Grady Booch and Jim Rumbaugh
I really find that a first-off of writing on paper or whiteboard is really crucial. Then move to UML if you want, but nothing beats the flexibility of just drawing it by hand at first.
You should definitely take a look at Steve McConnell's Code Complete-
and especially at his giveaway chapter on "Design in Construction"
You can download it from his website:
http://cc2e.com/File.ashx?cid=336
If you're developing for .NET, Microsoft have just published (as a free e-book!) the Application Architecture Guide 2.0b1. It provides loads of really good information about planning your architecture before writing any code.
If you were desperate I expect you could use large chunks of it for non-.NET-based architectures.
I'll preface this by saying that I do mostly web development where much of the architecture is already decided in advance (WebForms, now MVC) and most of my projects are reasonably small, one-person efforts that take less than a year. I also know going in that I'll have an ORM and DAL to handle my business object and data interaction, respectively. Recently, I've switched to using LINQ for this, so much of the "design" becomes database design and mapping via the DBML designer.
Typically, I work in a TDD (test driven development) manner. I don't spend a lot of time up front working on architectural or design details. I do gather the overall interaction of the user with the application via stories. I use the stories to work out the interaction design and discover the major components of the application. I do a lot of whiteboarding during this process with the customer -- sometimes capturing details with a digital camera if they seem important enough to keep in diagram form. Mainly my stories get captured in story form in a wiki. Eventually, the stories get organized into releases and iterations.
By this time I usually have a pretty good idea of the architecture. If it's complicated or there are unusual bits -- things that differ from my normal practices -- or I'm working with someone else (not typical), I'll diagram things (again on a whiteboard). The same is true of complicated interactions -- I may design the page layout and flow on a whiteboard, keeping it (or capturing via camera) until I'm done with that section. Once I have a general idea of where I'm going and what needs to be done first, I'll start writing tests for the first stories. Usually, this goes like: "Okay, to do that I'll need these classes. I'll start with this one and it needs to do this." Then I start merrily TDDing along and the architecture/design grows from the needs of the application.
Periodically, I'll find myself wanting to write some bits of code over again or think "this really smells" and I'll refactor my design to remove duplication or replace the smelly bits with something more elegant. Mostly, I'm concerned with getting the functionality down while following good design principles. I find that using known patterns and paying attention to good principles as you go along works out pretty well.
http://dn.codegear.com/article/31863
I use UML, and find that guide pretty useful and easy to read. Let me know if you need something different.
UML is a notation. It is a way of recording your design, but not (in my opinion) of doing a design. If you need to write things down, I would recommend UML, though, not because it's the "best" but because it is a standard which others probably already know how to read, and it beats inventing your own "standard".
I think the best introduction to UML is still UML Distilled, by Martin Fowler, because it's concise, gives pratical guidance on where to use it, and makes it clear you don't have to buy into the whole UML/RUP story for it to be useful
Doing design is hard.It can't really be captured in one StackOverflow answer. Unfortunately, my design skills, such as they are, have evolved over the years and so I don't have one source I can refer you to.
However, one model I have found useful is robustness analysis (google for it, but there's an intro here). If you have your use-cases for what the system should do, a domain model of what things are involved, then I've found robustness analysis a useful tool in connecting the two and working out what the key components of the system need to be.
But the best advice is read widely, think hard, and practice. It's not a purely teachable skill, you've got to actually do it.
I'm not smart enough to plan ahead more than a little. When I do plan ahead, my plans always come out wrong, but now I've spend n days on bad plans. My limit seems to be about 15 minutes on the whiteboard.
Basically, I do as little work as I can to find out whether I'm headed in the right direction.
I look at my design for critical questions: when A does B to C, will it be fast enough for D? If not, we need a different design. Each of these questions can be answer with a spike. If the spikes look good, then we have the design and it's time to expand on it.
I code in the direction of getting some real customer value as soon as possible, so a customer can tell me where I should be going.
Because I always get things wrong, I rely on refactoring to help me get them right. Refactoring is risky, so I have to write unit tests as I go. Writing unit tests after the fact is hard because of coupling, so I write my tests first. Staying disciplined about this stuff is hard, and a different brain sees things differently, so I like to have a buddy coding with me. My coding buddy has a nose, so I shower regularly.
Let's call it "Extreme Programming".
"White boards, sketches and Post-it notes are excellent design
tools. Complicated modeling tools have a tendency to be more
distracting than illuminating." From Practices of an Agile Developer
by Venkat Subramaniam and Andy Hunt.
I'm not convinced anything can be planned in advance before implementation. I've got 10 years experience, but that's only been at 4 companies (including 2 sites at one company, that were almost polar opposites), and almost all of my experience has been in terms of watching colossal cluster********s occur. I'm starting to think that stuff like refactoring is really the best way to do things, but at the same time I realize that my experience is limited, and I might just be reacting to what I've seen. What I'd really like to know is how to gain the best experience so I'm able to arrive at proper conclusions, but it seems like there's no shortcut and it just involves a lot of time seeing people doing things wrong :(. I'd really like to give a go at working at a company where people do things right (as evidenced by successful product deployments), to know whether I'm a just a contrarian bastard, or if I'm really as smart as I think I am.
I beg to differ: UML can be used for application architecture, but is more often used for technical architecture (frameworks, class or sequence diagrams, ...), because this is where those diagrams can most easily been kept in sync with the development.
Application Architecture occurs when you take some functional specifications (which describe the nature and flows of operations without making any assumptions about a future implementation), and you transform them into technical specifications.
Those specifications represent the applications you need for implementing some business and functional needs.
So if you need to process several large financial portfolios (functional specification), you may determine that you need to divide that large specification into:
a dispatcher to assign those heavy calculations to different servers
a launcher to make sure all calculation servers are up and running before starting to process those portfolios.
a GUI to be able to show what is going on.
a "common" component to develop the specific portfolio algorithms, independently of the rest of the application architecture, in order to facilitate unit testing, but also some functional and regression testing.
So basically, to think about application architecture is to decide what "group of files" you need to develop in a coherent way (you can not develop in the same group of files a launcher, a GUI, a dispatcher, ...: they would not be able to evolve at the same pace)
When an application architecture is well defined, each of its components is usually a good candidate for a configuration component, that is a group of file which can be versionned as a all into a VCS (Version Control System), meaning all its files will be labeled together every time you need to record a snapshot of that application (again, it would be hard to label all your system, each of its application can not be in a stable state at the same time)
I have been doing architecture for a while. I use BPML to first refine the business process and then use UML to capture various details! Third step generally is ERD! By the time you are done with BPML and UML your ERD will be fairly stable! No plan is perfect and no abstraction is going to be 100%. Plan on refactoring, goal is to minimize refactoring as much as possible!
I try to break my thinking down into two areas: a representation of the things I'm trying to manipulate, and what I intend to do with them.
When I'm trying to model the stuff I'm trying to manipulate, I come up with a series of discrete item definitions- an ecommerce site will have a SKU, a product, a customer, and so forth. I'll also have some non-material things that I'm working with- an order, or a category. Once I have all of the "nouns" in the system, I'll make a domain model that shows how these objects are related to each other- an order has a customer and multiple SKUs, many skus are grouped into a product, and so on.
These domain models can be represented as UML domain models, class diagrams, and SQL ERD's.
Once I have the nouns of the system figured out, I move on to the verbs- for instance, the operations that each of these items go through to commit an order. These usually map pretty well to use cases from my functional requirements- the easiest way to express these that I've found is UML sequence, activity, or collaboration diagrams or swimlane diagrams.
It's important to think of this as an iterative process; I'll do a little corner of the domain, and then work on the actions, and then go back. Ideally I'll have time to write code to try stuff out as I'm going along- you never want the design to get too far ahead of the application. This process is usually terrible if you think that you are building the complete and final architecture for everything; really, all you're trying to do is establish the basic foundations that the team will be sharing in common as they move through development. You're mostly creating a shared vocabulary for team members to use as they describe the system, not laying down the law for how it's gotta be done.
I find myself having trouble fully thinking a system out before coding it. It's just too easy to only bring a cursory glance to some components which you only later realize are much more complicated than you thought they were.
One solution is to just try really hard. Write UML everywhere. Go through every class. Think how it will interact with your other classes. This is difficult to do.
What I like doing is to make a general overview at first. I don't like UML, but I do like drawing diagrams which get the point across. Then I begin to implement it. Even while I'm just writing out the class structure with empty methods, I often see things that I missed earlier, so then I update my design. As I'm coding, I'll realize I need to do something differently, so I'll update my design. It's an iterative process. The concept of "design everything first, and then implement it all" is known as the waterfall model, and I think others have shown it's a bad way of doing software.
Try Archimate.