Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
When first approaching a project is best to step back and think through everything or just dive in and start coding and polish at a later date? Essentially, do you design first or try to rapidly prototype?
I have been burned by both methods, sometimes I try and think everything through but when I actually get down to the nitty gritty I encounter problems that I didn't take in consideration, and sometimes when I code first I end with code that needs to redone to fit in with a better overall design. Alot of my problems stem from inexperience, but any advice is welcome.
Go incrementally and iteratively.
Design a bit, implement a bit.
Starting with a design you can suffer from a tunnel effect where you cannot have any real feedback before you actually implement something.
Starting without design, you can take decisions you'll regret.
The ideal situation is to be able to implement a very skeletal end-to-end version of your system that can be tested, and demonstrated to the customer.
It is always safer to design first, but this does not mean prototyping does not work. The real problem with prototyping is resisting the urge to keep the code you already wrote instead of throwing it away when the time comes to do the design.
There is no silver bullet. It seems like design first is the preferred approach. But you will not be able to predict all complications that can arise while implementing your design. Some of them could potentially be show stoppers. Plus, if you're writing for a client, it's good to be able to show something just to make sure that you're on the same page.
At my workplace we do both - we do a rapid prototype, just to get feedback and get an idea of any potential problems. Then we do a formal design and formal implementation. In most cases we are able to salvage a lot of code from the prototyping stage. I like this approach, since we usually end up with clean, maintainable code.
See Gall's Law. The key is to iterate: design a little, implement a little, test a little, then repeat until you (or your customers) are satisfied. This is the essence of the new breed of "agile" methodologies.
It depends.
Prototyping is most useful when the requirements or a solution aren't necessarily clear. As an example, I am doing a data warehousing project in an environment (large commercial insurance) where financial reconciliation is a big deal. This project has involved a large prototyping exercise to get a system that will reconcile to the financials. As the business rules surrounding this were not well documented, the prototype was instrumental in exposing all of the corner cases.
In other cases, a design-first approach might be more appropriate. This is most applicable where requirements and a sensible solution architecture are reasonably obvious.
You must have some idea of a cohesive architecture before you start working. This is especially true of large scale systems.
Prototyping could be used for particular aspects of the design, e.g. presentation layer.
I think it depends on what kind of business requirements you have up-front. If they are (relatively) detailed and complete, then I'd design based on those requirements. If you have barely anything to work with in the beginning, then prototype out and show your customer what you got, to receive further requirement info.
You should develop using Agile Methodologies. Simply put, you design has you go. The team together with the product owner define a list of topics to develop, order them by importance, and split the development in iterations. Each iteration as features to be developed and on the start of the iteration is design each feature.
See more here.
When first approaching a project, prototype. But don't prototype everything. Prototype one important thing (one "use case" if that means anything) and "turn the inner eye to follow its path" - keep an eye out for the practical problems you encounter in trying to get that one thing done.
Now that you have some idea what it takes to do an important thing, you can design from more than just first principles.
Of course, this assumes you're working in an environment where you can turn out prototypes at minimal cost to ongoing development efforts. But if you're working in such an environment, pepper your design discussions liberally with prototypes. With any luck you may get to keep some of them.
note that agile methods are not an excuse to avoid designing, they just encourage testing of the design more frequently, and in smaller increments
i like to sketch the design and break its elements down until reasonably sure that there are no obvious unknowns or risks; unknowns and risks are highlighted for 'spike' projects, with a time-box for determining feasibility and notes on possible alternatives if the preferred methods prove unworkable
once comfortable with the overall architecture, jump into the features bottom-up (or in priority order) to complete the design, write the initial tests, then implement
EDIT: note that the question "design or prototype first" is making a bad assumption, i.e. that it is possible to prototype without doing any design, which of course is not the case (unless you are using the million-monkeys methodology)
Design first, unless you're willing to take the risk of throwing out all the work put into your prototype when you find it can't do what you need it to do. At a minimum, you should make some high level designs for your project that can help you make some decisions about how you're going to build your prototype so that you will have a minimum of wasted effort.
If I know what I want to build, I just go right to design.
If I'm building something for a client, then I prototype to ease out more specific requirements from the users.
Maybe not an answer but a suggestion from my experience.
In most cases I'd be better off if I had started coding earlier. You can design until the cow comes home, but if the cows are on the horizon when you start coding, you might find your careful design hard to implement in time.
Related
I have an idea for a business that requires a well designed web application. I'm not a rocket surgeon, but I'm smart enough to know that you get what you pay for and am willing to pay for talent. However, I want the development process to go as smoothly as possible and would like to know how to make that happen.
So, what information do developers need (or want) initially from the owner to avoid having to make assumptions about business (or other) requirements? Do I need to create state transition diagrams or write use cases?
Essentially, how do I take the concept in my head and package it in a way that allows the developer to do what they do best? (assuming that is creating good software. haha)
Any advice is appreciated.
Shawn
You may need to reword your question, as it is too general to get a good answer, so some vague details would be helpful.
But, the better vision you have of what you want the smoother it will be.
I find UML diagrams too confining, when you aren't going to be doing the work, as you may not come up with the best design.
So, if you start with designing out what each page should look like, as you envision it, then you can write up use cases, which are short scenarios.
So, you may write up:
A user needs to be able to log in using OpenID.
This will tell the developer one function that you want, and who you expect to do that action.
But, don't put in technologies, as you may think that a SOAP service is your best bet, but upon talking about it you may find that there is a better solution.
Use cases are good points to show what you are envisioning, and give text to your page designs.
Talk to the developers. Explain what you want and why you want it. Together you make the flow charts and whatnot. Writing requirements is part of the design process, and it's a good idea to have the developers onboard as soon as possible. Start simple and small, then grow and expand while iterating.
In talking over web services before, I have found the best starting point is drawing on a sheet of paper what you think the site will look like, and add in a few arrows from things you want clickable to the pages that should result. Keep it simple, nothing too fancy, and hopefully you and the developer can come to an understanding of what you want pretty quickly.
Use cases might be best for checking off all the points later in the project about how complete your site is; I haven't really found it to be a helpful starting point, but I'm sure others disagree. (They just seem too tedius to read when actually writing code.)
Same with state transition diagrams; they are too tedious and I think most developers will assume you made mistakes in them anyway. :) Everyone else does... Unless your project hinges very tightly on the correctness of a state machine, I wouldn't really bother.
This book contains some good advice on what constitutes a good statement of requirements from a programmers point of view. It also has the useful guideline of not trying to set the form of your requirements too early, and a substantial piece on describing the problem you are trying to solve.
I like UI mockups based on actual program/site flows e.g registering a customer or placing order. Diagrams/pictures of GUIs with structured, consistent data examples are unambiguous.
I agree that UML and use cases are only really useful if everyone speaks UML and the projects are of sufficient complexity (few are).
You may want to read up on Agile/Scrum techniques. These are becoming a sort of standard and when properly managed can save weeks of development time.
I find that words don't do a good job of communicating how a system is supposed to work. Wireframes, white-board drawings/transition diagrams, and low-fidelity prototypes are great ways to communicate a concrete idea. One example of a low-fidelity prototype is a "clickable" paper prototype that allows a user to touch "buttons" on paper to go from one drawing to another. It costs very little time (cheaper), but goes a long way to communicate an idea between two parties.
Stay away from formal documentation, UML diagrams, or class (technical documentation) diagrams that don't speak to you. This is what large, risk-averse companies move toward to be more "mature". These are also byproducts of an idea that is hashed out, and it sounds like you're in the hashing out stage.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
If everything in scrum is all about functional things that a user can see is there really any place for refactoring code unrelated to any new functional requirements?
I don't think that this has as much to do with Scrum as it does with project management philosophy.
Regardless of whether a project uses Scrum or not, many project managers do not like developers spending time on "unnecessary" things like code refactoring or restructuring that doesn't directly advance one of the outstanding functional requirements. It's not "work that yields results" like normal development, it's "work that prevents a delay of results later". Given the typically short time-lines used for Sprints, the benefit is often hard to see and nearly impossible to quantify.
Keeping code maintainable needs to be an item on your burn-down list (if you use a Scrum). It is just as important as new development. While it may not seem like something that is "visible to the user", ignoring it increases your technical debt. Down the road when the technical debt piles up enough that your code's lack of maintainability slows down development, the delays in new feature development will be visible to customers.
It's all a matter of management/philosophy. Instead of looking at refactoring and maintainability enhancements as "extra" work that doesn't impact customers, it should be viewed as a time investment to prevent customer-visible delays (and potentially bugs as well) down the road. Developers can sometimes see these benefits more clearly than managers can; if your manager doesn't understand the disadvantages of neglecting maintainability, you might want to grab several other developers and have a chat with your manager.
I think there is a fair case to make for technical debt refactoring where the effort/cost impact of maintaining the code is as high as, or higher even, than the cost of refactoring it to improve quality or work better / properly - specifically to lend it a higher degree of maintainability.
eg: if the software is so problematic you are losing customers, or money, you'd act fast to fix it.. Some might argue this is a business requirement of it's own, but it's often not placed front and centre on small to mid sized development projects, which instead focus on the technicalities of creating apps rather than the impact of the quality of the app on the bottom line.
I think you are probably talking about large scale refactoring rather than the continuous refactoring you would do whilst in the whole red-green-refactor cycle.
My approach would be something like this, if reafactoring an old feature makes it easier to add a new feature then go ahead and do it. But in some ways you are right, if there is no pressure on a particular unit to change (i.e. it is completely finished and will never change again and will never impact on other modules) then there is no practical need to refactor. However I rarely find a module that is quite so finalised.
If everything in Scrum is all about functional things that a user can see (...)
Any project and methodology should be about generating business value, you rarely do things just for the fun in a business environment. Having that said, I see quality in Scrum (and other Agile methods) as a way to not kill your velocity on the long run and, ultimately to achieve hyper productivity. I thus believe that a typical "Definition of Done" should include something like "no increase of technical debt" (put your quality standards in there). If you think a new feature will impact existing code that should be refactored, include this cost in the estimate (or create a refactoring item in your Product Backlog) and explain things to your Product Owner. Because at the end, it's up to the Product Owner to prioritize items and to decide if quality can be sacrificed temporarily (if your business die because you don't release a feature, what is the point of refactoring existing code?). But he must be aware that this can't be a long term strategy or he will kill the team velocity.
bta: Regardless of whether a project uses Scrum or not, many project managers do not like developers spending time on "unnecessary" things like code refactoring or restructuring that doesn't directly advance one of the outstanding functional requirements.
Definitely a noteworthy observation; my solution to this would be as follows:
Perform regular code reviews. Every code review should recommend actions to improve on deficiencies in the code.
There is now a requirement for jobs which improve code quality. Build these into the sprint and track them in the same way as any other job.
If your manager needs any more convincing, cast 'the maintainer' as a user, and describe some user stories for them - and then 'features' are things like 'the code is fully commented with xml doc comments' and 'the code does not produce any warnings from ReSharper'
If you can justify it as part of the process of completing other tasks by identifying issues/risks with current sets of code, and it is a better end result, go for it. But don't get overzealous and screw the timelines/budget.
Closed. This question is opinion-based. It is not currently accepting answers.
Closed 3 years ago.
Locked. This question and its answers are locked because the question is off-topic but has historical significance. It is not currently accepting new answers or interactions.
I have been working on a list for a while that helps me share the why of programming approach and thought as much as how to do something.
For this, I wanted to build a list of things that are:
best practice,
best thought,
best approach...
that help a programmer's ability to analyze, think, approach, solve and implement in the most effective way.
I have seen dozens of incredibly valuable comments in questions throughout Stack Overflow, but I couldn't find a place where we keep them together. There is the most controversial opinion on Stack Overflow. However, I'm just looking for sagely insights that can be shared and help my team, and I approach and solve problems better through better programming.
Hopefully this can be one place to gather the one or two liners that are concise, profound and easy to share, repeat, review. If we keep it to one rule per answer it might be easiest to vote up/down.
I'll start with the first.
DRY - Don't Repeat Yourself - In code, comments or documentation.
Always leave the code a little better than when you found it.
Code does not exist until entered into a versioning control system.
Don't be afraid to admit "I don't know" and ask.
10 minutes asking someone could save a day pulling your hair out!
KISS - Keep it simple, stupid.
Pick the simplest solution that works.
Don't make things (too) complicated before they need to be.
Just because everyone else is using some complicated framework to solve their problem, doesn't mean you have to.
Don't reinvent the wheel
If there ought to be a function for it in the core library - there probably is.
Maintainability is important.
Write code as if the person who will end up maintaining it is crazy and knows where you live.
Someone else won't fix it.
If a problem comes to your attention, take ownership long enough to ensure it will be taken care of one way or another.
Don't optimize unless there's a demonstrable problem.
Most of the time when people try to optimize code before it's been proved necessary, they'll spend a lot of resources, make the code harder to read and maintain, and achieve no noticeable effect. Sometimes they'll even make it worse.
"We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil."
- Donald Knuth
How hard can it be?
Don't let any problem intimidate you.
Don't Gather Requirements -- Dig for Them
Requirements rarely lie on the surface. They're buried deep beneath layers of assumptions, misconceptions, and politics
via The Pragmatic Programmer
Follow the SOLID principles:
Single Responsibility Principle (SRP)
There should never be more than one reason for a class to change.
Open-Closed Principle (OCP)
Software entities (classes, modules, functions, etc.)
should be open for extension, but closed for
modification.
Liskov Substitution Principle (LSP)
Functions that use pointers or references to base
classes must be able to use objects of derived classes
without knowing it.
Interface Segregation Principle (ISP)
Clients should not be forced to depend upon interfaces
that they do not use.
Dependency Inversion Principle (DIP)
A. High level modules should not depend upon low
level modules. Both should depend upon abstractions.
B. Abstractions should not depend upon details. Details
should depend upon abstractions.
Best Practice: Use your brain
Don't follow any trend/principle/pattern without thinking about it
I think almost everything that is listed under "The Zen of Python" applies for every "Rules of Programming Mindset" list. Start with 'python -c "import this"':
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than right now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
Test Driven Development (TDD) makes coders sleep better at night
Just to clarify: Some people seem to think TDD is just an incompetent coder's way of limping from A to B without borking everything up too much, and that if you know what you're doing, that means there is no need for (unit) testing methodologies. That completely misses the point of Test Driven Development. TDD is about three (update: apparently four) things:
Refactoring magic. Having a full set of tests means you can make otherwise insane refactoring stunts, juggling the entire structure of your application without missing even one of the two hundred crazy subtle side effects that result from it. Even the best programmers are reluctant to refactor their core classes and interfaces without good (unit) test coverage, because it's damn near impossible to track down all the little 'ripple effects' it causes without them.
Detecting pitfalls early. If you are writing tests the right way, it means forcing yourself to consider all the fringe cases. Often, this leads to better design choices once the actual development begins, because the coder has already considered some of the trickier situations that may call for a different inheritance structure or a more flexible design pattern. The need for these changes is often not apparent - or intuitive - during initial planning and analysis, but those exact changes can make the application much easier to extend and maintain down the line.
Ensuring that tests get written. TDD requires you to write the tests before writing the code. Sure, that can be a pain in the ass, since writing tests is tedious compared to writing actual code - and often takes longer, too. However, doing so is the only way to make sure the tests will be written at all. If you think you'll remember to write the tests once the code is done, you're almost always wrong.
Forcing you to write better code. Since TDD forces all code to be testable (you don't write code before there is a test for it), it requires you write more decoupled code so that you can test the components in isolation. So TDD forces you to write better code. (Thanks, Esko)
Google before you ask your colleague and interrupt his coding.
Less code is better than more, as long as it makes more sense than lots of code.
Habits of the lazy coder
The first time you are asked to do something, do it (right).
The second time you are asked to do it, make a tool that does it automatically.
And the third time, if the tool doesn't cut it, design a domain specific language for generating more tools.
(not to be taken too seriously)
Be a Catalyst for Change
You can't force change on people. Instead, show them how the future might be and help them participate in creating it.
via The Pragmatic Programmer
Don't Panic When Debugging
Take a deep breath and THINK! about what could be causing the bug.
via The Pragmatic Programmer
You may copy and paste to get it working, but you may not leave it that way.
Duplicated code is an intermediate step, not a final product.
It's Both What You Say and the Way You Say It
There's no point in having great ideas if you don't communicate them effectively.
via The Pragmatic Programmer
Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.
From: Coding Horror
Build Breaker Buys Lunch
Publish Early, Publish Often
Build it correct first. Make it fast second.
Frequently conduct code reviews
Code review and consequently refactoring is an ongoing task. Here is a few goodies about code review in my opinion:
It improves code quality.
It helps refactor reusable codes into reusable libraries.
It helps you learn from your fellow developers.
It helps you learn from your mistakes and refresh your memory about a genius code you have written before.
Anything that could affect how the application runs should be treated as code, and that means putting it in version control. Especially build scripts and database schema and data (.sql) files.
Take part in open source development
If you are using open source code in your projects, remember to post your bugfixes and improvements back to the community. It's not a development best practice per se, but it's definitely a programmer mindset to strive for.
Understand the tools you use
Don't use a pattern until you've understood why you're using it; don't use a tool without knowing why; don't rely on your framework or language designer always being right for your situation, but also don't assume they're wrong until proven to be!
Convention over Configuration
Especially where conventions are strong and some flexibility can be sacrificed.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
Does the functional spec help or hinder your expectations? Do programmers who practice the waterfall methodology, are they open to functional specs? I'm a web designer/developer working with a team of 5 programmers and would like to write a functional spec to explain what we need, so that when I begin my work - I know we are working towards the same goal.
I won't start any freelance project until I've got a design spec and functional spec written up and signed off. There's too much room for rogue clients to nickel and dime you to death if you don't have it. The functional spec allows you to stay on target/focused and gives you a natural check list to work to.
If there's no functional spec then you get all the "what ifs" starting to creep in and developers thinking - you know, this would be useful, and it'll only take me an hour. Sure an hour to code the prototype and get it basically working - plus the day to design all the tests and make sure all test cases are covered, then another couple of days to iron out all the bugs, then time to write the documentation. There's far too much room for what seems like a trivial addition to be inserted when there's no spec. You've no doubt heard of the infamous "scope creep". There's also far too much room for clients to say "that's not what I wanted..." when you deliver it and try and wriggle out of paying you.
If you've got the design spec and the functional spec written up ahead of the development and both you and the client have signed off that your understanding of not only the basic details but all the nuances of the language used is one and the same - only then can the real work begin.
There are a couple of anecdotes out there the first is quite true, while the other is a common misconception:
Software development is only 15% about the code, the rest is resource/people management.
It takes 20% of the time to complete the first 80% of the project and the remaining 80% of the time to complete the last 20%.
The misconception is that a working prototype is 80% of the way there - don't be fooled, it is not. So it's easy for a client to say "what's taking so long, I thought you were almost done!" and then quibble that they're paying too much for something that should've been finished months ago. Some of the design methodologies out there really lend themselves well to this popular misconception. The waterfall design methodology is one of them if it's not used correctly.
My view is make sure your understanding is the same, both sign off. Set milestones and make the client very aware at the outset that prototypes are a long way from the completion of the project and set expectations right from the outset as to what those milestones are and when the client can expect to see them delivered.
For project managers of development teams documentation and expectations are everything. You can't live without it, it's the only form of recourse you have against "That's not what I said" or "That's not what I meant" and ergo "I'm not paying you".
I learned from a lot of mistakes made by far more qualified developers than me and saw what it did to them. The two most important documents for your project are the design spec and the functional spec. Don't leave home without them or it can [or most likely will] come back and bite you in the ass.
Addendum re: User Stories:
An additional note about user stories is that they're great for what they are. They should be included in your functional specification but shouldn't be your functional specification.
A user story only describes a single task. It is very lightweight and doesn't contain excessive detail. As the common recommendations go, it should fit on a 3x5 card...if you as a project manager handed me a 3x5 card and told me to write a piece of software based on what I read, no doubt it would be handed to the user at the end and they'd tell the project manager that's not what they wanted.
You need a far greater level of detail in a functional spec. It shouldn't be limited to basic workflows. A functional spec is a whole bunch of user stories along with notes on interpretation of those user stories, improvements that can be made to them, common tasks that can be combined to improve efficiency. The list goes on.
So user stories are a good beginning, but they're not a replacement for a functional spec, they're bullet points in a functional spec.
I work with mostly the Waterfall model, and solely with functional specs. When working on my own (where I can set my own model and program any way I want) I start by writing up functional specs and then implementing them. It gives me a much better idea of the size and scope of the work, helps me estimate the time involved, and helps ensure that I don't miss anything.
Also, you can pass this document to:
Users so that they can make their requirements clear
Developers to create the functionality
Testers to make sure they are testing the right thing
Architects so that they can analyze the requirements
Using functional requirements over user stories is a matter of preference and the scope of the project. If you have a small user base, then you may be able to get away with user stories (which outline various event sequences the user might do), but for larger projects, you should use functional requirements as they have more detail and lead to fewer misunderstandings. Think of them as a means of communication with all people involved in the project.
Frankly, the Functional Specifications should already be part of your Big-M (Waterfall) methodology. Your functional specification is WHAT you are going to build; not necessarily how you are going to build it (which would be your detailed design/specification and the next step in the waterfall).
If you haven't written one yet, stop what you are doing and write one. You are just waste time if you do otherwise. You can start here with Joel's article.
It took me more than 10 years to get it beat into my head to write a functional spec before doing any code. Now I will write one for anything taking more than a day to write. The level of detail, and level of assumptions should be as much as needed to clearly define what needs to be done and communicate it to others (or remind yourself), anything beyond that is a waste.
Others prefer User Stories ... which is fine too, as long as you do some kind of planning.
Another way to accomplish this is using user stories
I find well-written functional specs very useful. A well organized functional specification can also help organize your tests (many-to-many mapping from individual requirements to test cases).
<p style="tongue: in-cheek">They also prove useful for finger-pointing in larger organizations (The requirements were inaccurate! The implementation didn't follow the requirement! QA didn't properly test this requirement! etc.)</p>
I'll second Codeslave's reference to Painless Functional Specification. It's a good series of articles on specifications. See also this Stackoverflow post for a discussion on what content to put into functional specs.
I've done a few large projects, including one with some hundereds of person-years of total effort. As a project team gets larger the number of informal communication channels goes up with a quadratic upper bound. Without a spec this informal communication mechanism is the only way things can get communicated. With a spec, the communication channels approach a hub-and-spokes, making the growth more like a linear function of the project team size.
A spec is really the only scalable way to to get the team 'singing off the same hymn sheet'. There should be some review and negotiation about the spec, but ultimately someone has to take ownership of this to avoid the project becoming a free-for-all.
I think they're a lovely idea, and should be tried.
Just a few comments on some of the answers here...
First of all, I do believe that a good spec document is important for any moderatly complex requirement (and definitly for highly complex ones). But make sure it is a good spec i.e. don't just state the obvious (like one poster already mentioned) but also don't leave out those parts that may seem trivial to you (or even the developers) since you might have more knowledge of that part of the system than some others involved (e.g. testers or documenters) which will appreciate the otherwise "missing bits".
And if your spec is good, it will get read - in my experience (and I've written and read lots of specs over the last years) it's the bad specs that get dumped and the good ones that get followed.
Concerning user stories (or sometimes also called use cases): I think these are important to get an idea of the scenario, but they usually can't replace the details (e.g. screen mockups, how where and if a feature is configurable, data model, migration issues etc.) so you'll probably need both for more complex requirements.
In my experience, functional specs have a fine line between not saying enough and saying too much.
If they don't say enough, then they leave areas open to misunderstanding.
If they say too much, they don't leave enough "wiggle room" to improve the solution.
And they should always be open to a process of revision.
It depends on the functional specification. I've had functional specifications where the writer knew the system inside and out, and wrote the specification as such, and I've had other writers write it with just what they expected to see as a user.
With the former, it's easier because I know exactly what I need to write and where I need to write it, but it limits how easily I can refactor the existing code, since estimates took into account just this feature, and not refactoring existing code that it touches.
With the latter, I have freedom to refactor (so long as end functionality is the same), but if it's a system I'm unfamiliar with, the time estimate is harder to make.
Overall, I love functional specifications -- I also like to remind people that they're written on paper that bends, and as such, should be flexible.
Whether you call them functional specs, business requirements, or user stories, they are all very beneficial to the development process.
The issue with them comes when they are chiseled in stone and used as a device to pass blame around when the system utimately doesn't fit with the user's real needs. I prefer to use the functionals or requirements as a starting point for an iterative process not as the bible for exactly how the system will look when it is complete. Things change, and users typically don't have an understanding of what they want until they have something (a working prototype possibly) in their hands that they can work with instead of conceptualizing on a piece of paper how it will function in the real world. The most successful projects I've implemented were ones where the development team and the users were closely aligned and were able to rapidly turn around changes instead of holding people to what they wanted on a piece of paper six months ago.
Of course this process wouldn't work if you were in a fixed-bid type of situation as one of the earlier answers pointed out.
One interesting substitute for a func spec or user stories that I have seen advocated is to write a user manual for the software first.
Even if this is only notional (i.e. if you do not intend to ship any manual - which you probably shouldn't as nobody will read it), it can be a useful and reasonably lightweight way to reach a common understanding of what the software will do and look like. And it forces you to do the design up front.
I've found that even if you write Functional Specs a lot of the detail is sometimes lost on the person you are trying to address. Now if a Functional Spec is written along with some kind of UI mockup, that makes a huge difference. UI mockups not only show the user what you are envisioning, it also triggers users into remembering things they wouldn't have thought off in the first place.
I have seen and written many specs, some were very good, most weren't. The main thing that they all had in common is that they were never followed. They all had cobwebs on them by the 3rd day of coding.
Write the spec if you want, the best time to do it is at the end of the project. It will be useless for developers to follow but it will at least be an accurate representation of what was done (I know- not really a spec). But don't expect the spec to get the code written for you. That is the real job. If you don't know what to write talk to your stakeholders and users and get some good user stories and then get on with it.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
We prototype a design, GUI, just to analyze a particular problem, proof of concept, etc. Sometimes we throw away the prototype, and sometimes it ends up in the production code. We use different languages, technologies, strategies, and styles to prototype.
What are the different situations you prototype usually and how do you prototype? Any good resource out there to master the craft?
One hot title is Effective Prototyping for Software Makers. The issue is that there are several schools of thought.
Rapid Prototyping. Use fancy tools; get
something done soon.
Evolutionary Prototyping. Evolve from prototype to production.
Some of this is legacy thinking, based on an era where tools were primitive and projects had to be meticulously planned from the beginning. When I started in this industry, the "green-screen" character-mode applications where rocket science and very painful to mock up. Tools and formal techniques were essential to manage the costs and risks.
This thinking is trumped by some more recent thinking.
Powerful tools remove the need for complex prototypes. HTML mockups can be slapped together quickly. Is it still a prototype when you barely have to budget or plan for it?
[You can mock it up in MS-Word and save it as HTML. It's quicker for a Business Analyst to do it than to specify it and have a programmer do it.]
Also, powerful tools can reduce the cost of mistakes. If it only took a week to put something together -- production-ready -- what's the point of an formal prototype effort?
Agile techniques reduce the need to do quite so much detailed up-front planning. When you put something that works in the hands of users quickly, you don't have quite so much need to be sure every nuance is right before you start. It just has to be good enough to consider it progress.
What can happen is the following. [The hidden question is: is this still "prototyping" -- or is this just an Agile approach with powerful tools?]
Using tools like Django, you can put together the essential, core data structure and exercise it almost immediately. Use the default Django admin pages and you should be up and running as soon as you can articulate the data structures and write load utilities.
Then, add presentation pages wrapped around real, working data. Be sure you've got things right. Since you've only built data model and template-driven HTML pages, your investment is minimal. Explore.
Iterate until people start asking for smarter transactions than those available in the default admin pages. At this point, you're moving away from "discovery" and "elaboration" and into "construction". Did you do any prototyping? I suppose each HTML template you discarded was a kind of prototype. For that matter, so where the ones you kept.
The whole time, you can be working with more-or-less live, production users.
Personally, I believe a true prototype should not be much more than diagrams drawn on paper to demonstrate the flow of whatever it is you are trying to achieve. You can then use these documented flows to run through several scenarios to see if it works with whoever has requested the functionality.
Once the paper prototype has been modified to a point where it works then use it as a basis to start coding properly.
The benefits of this process are that you can't end up actually using the prototype code in production because there isn't any. Also, it is much easier to test it with business experts as there is not any code for them to understand.
Right now I just draw pictures. I would like to do more, but to get something to a point where the users would understand any better than a picture would cost to much time.
I am interested in seeing some of these responses :)
I should mention where I work is just me and one other guy to play the roles of project manager (collect data, design spec & app), dbas, coders, tool researcher/developer, et al that comes with the job of making an app for a small company.
For webapps, start with an pure (x)HTML + CSS mock-up, and then use a framework that makes it easy to implement the functionality.
Template-based frameworks are very good for this, but we've had some good experiences with JSF + Facelets + Seam, too.
The main reason for doing prototypes is reducing risk. Thus, we do UI prototypes, which are really not very helpful unless they actually do something that a user can play around with. Just as important, we also do prototypes to either prove that something can work or figure out how something does work.
I start off making a prototype that makes the most interesting part work, then I throw it away and move on to a new, more interesting project...
*kills self*