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
In the course of your software development lifecycle, what essential design artifacts do you produce? What makes them essential to your practice?
The project I'm currently on has been in production for 8+ years. This web application has been actively enhanced and maintained over that time. While we have CMMI based policies and processes in place, with portions of our practice being well defined, the design phase has been largely overlooked. Best practices, anyone?
Having worked on a lot of waterfall projects in the past and a lot of adhoc and agile projects more recently, there's a number of design artifacts I like to create although I can't state enough that it really depends on the details of the project (methodology/team structure/timescale/tools etc).
For a generic, server-based 'enterprise application' I'd want the bare minimum to be something along these lines:
A detailed functional design document (aka spec). Generally something along the lines of Joel s' WhatsTimeIsIt example spec, although probably with some UML use-case diagrams.
A software techical design document. Not necessarily detailed for 100% system coverage but detailed in all the key areas and containing all the design decisions. Being a bit of an UML freak it'd be nice to see lots of pictures along the lines of package diagrams, component diagrams, key feature class diagrams, and probably some sequence diagrams thrown in for good measure.
An infrastructure design document. Probably with UML deployment diagram for the conceptual deisng and perhaps a network diagram for something more physical.
When I say document any of the above might be broken down into multiple documents, or perhaps stored on a wiki/some other tool.
As for their usefulness, my philosophy has always been that a development team should always be able to hand over an application to a support team without having to hand over their phone numbers. If the design artifacts don't clealry indicate what the application does, how it does it, and where it does it then you know the support team are going to give the app the same care and attention they would a rabid dog.
I should mention I'm not vindicating the practice of handing software over from a dev team to a support team once it's finished, which raises all manner of interesting issues, I'm just saying it should be possible if the management so desired.
Working code...and whiteboard drawings.
:P
Designs change so much during development and afterwards that most of my carefully crafted documents rot away in source control and become almost more of a hindrance than a help, once code is in production. I see design documents as necessary to good communication and to clarify your thinking while you develop something, but after that it takes a herculean effort to keep them properly maintained.
I do take pictures of whiteboards and save the JPEGs to source control. Those are some of my best design docs!
In our model (which is fairly specific to business process applications) the design artefacts include:
a domain data model, with comments on each entity and attribute
a properties file listing all the modify and create triggers on each entity, calculated attributes, validators and other business logic
a set of screen definitions (view model)
However do these really count as design artefacts? Our framework is such that these definitions are used to generate the actual code of the system, so maybe they go beyond design.
But the fact that they serve double duty is powerful because they are, by definition, up to date and synchronised with the code at all times.
This is not a design document, per se, but our unit tests serve the dual purpose of "describing" how the code they test is supposed to function. The nice part about this is that they never get out of date, since our unit tests must pass for our build to succeed.
I don't think anything can take the place of a good old fashioned design spec for the following reasons:
It serves as a means of communicating how you will build an application to others.
It lets you get ideas out of your head so you don't worry about tracking a million things at the same time.
If you have to pause a project and return to it later you're not starting your thought process over again.
I like to see various bits of info in a design spec:
General explanation of your approach to the challenge at hand
How will you monitor your application?
What are the security concerns and how are they addressed?
Flowcharts / sequence diagrams
Open issues
Known limitations
Unit tests, while a fantastic and arguably critical item to include in your application development, don't cover all of these topics.
Related
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 4 years ago.
Improve this question
I've studied and implemented design patterns for a few years now, and I'm wondering. What are some of the newer design patterns (since the GOF)? Also, what should one, similar to myself, study [in the way of software design] next?
Note: I've been using TDD, and UML for some time now. I'm curious about the newer paradigm shifts, and or newer design patterns.
There is roughly an infinite number of design patterns. Design patterns are just that: a recurrence of tricks programmers use to get things done. The most useful thing about the GoF patterns is how famous they are. In that, they have become a language -- exactly what the GoF hoped to achieve.
Many other patterns you'll find on the web and in literature are "just" useful tricks, not so much a language you can use when you speak to fellow programmers. That said, there is a number of patterns that arose in the past ten years or so, particularly in the realm of web development. See the patterns listed in Martin Fowler's patterns book.
I'm surprised that no one has mentioned Martin Fowler's book Patterns of Enterprise Application Architecture. This is an outstanding book with dozens of patterns, many of which are used in modern ORM design (repository, active record), along with a number of UI layer patterns. Highly recommended.
I am an avid follower and supporter of the PCMEF (now PCBMER) framework
Here's a simpler overview of it.
It kind of understands that enterprise systems are huge an complex, and by combining a bunch of other design patterns together into the PCMBER framework (Presentation, Control, Mediator, Entity and Resource), even the most complex system remain easy to usnerstand and manage.
One of the newer ones that I found particularly useful is Domain Driven Design. Not so much a pattern in its own right, but more of a mindset - to concentrate on the domain objects - i.e. the things that you model and build the rest of application around it.
I found that it gave meaning to principles that we all knew before but were too lazy to deal with - like Single Responsibility Principle and Separation of Concerns. I take those two especially more seriously now.
Another axis of improvement for me was TDD and Dependency Injection. I have discovered that with lots of interfaces and classes implementing them I was able to let go of this fear of only defining something once. That is not to say that it is in conflict with DRY(Don't Repeat Yourself) much. It's OK to have two classes with the same properties if their purposes are different. Encapsulation and SRP are much more important than only defining a property once.
Umm...none of the things people have mentioned are design patterns.
GOF was written implicitly with Java in mind. It explored that space pretty well. However once you go into other languages some patterns are no longer necessary (Observer is rarely used in a language like C# that supports events) and some new ones spring forth. Grab yourself the Pro JavaScript Design Patterns or Design Patterns In Ruby books and see what happens to the stand-by pattens in these very different paradigms.
My favorites lately have come from leaning on the functional drift of modern languages. I'm a big fan of nested closures and of the functional ways of tackling some of the same problems that GoF does (again, see the Ruby book for great examples). I also am currently in love with the idea of internal domain-specific languages which open up into a whole series of design patterns of their own (including nested closures). Also event-aggregation seems to be poised to hit it big in the .Net world in the near future.
A couple other big ones that have hit the scene but aren't discussed as much in GoF - probably because they are more high level then what those guys were going for - are Inversion Of Control Containers, Message Bussing, Aspect-Oriented-Programming, Model-View-Controller, Model-View-Presenter, Model-View-ViewModel, and their ilk.
By the way, these are not design patterns, but if you're looking to progress beyond TDD start looking into Behavior-Driven-Development and Context/Specification.
A huge change from a maintenance aspect is the use of DVCS. If you don't know what one is or haven't used one, I highly suggest reading up on the two hard hitters:
Mercurial (hg): https://www.mercurial-scm.org/
git : http://git-scm.com/
They've done quite a bit to change the workflow of the common programming environment. Not really a pattern/design I spose, but I don't think TDD or UML are technical patterns/designs either at some level. Maybe more like common practices surrounding programming.
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
My question is in regard to referencing open source frameworks. There are many of them for many different purposes. I personally leverage several of them in a single project. For example:
Unity
CAL/Prism
ValidationAspects
EnterpriseLibrary Logging
EnterpriseLibrary Exception Handling
EnterpriseLibrary Caching
Caliburn
All of these frameworks have helped greatly from a development effort perspective. There are however some negative aspects involved:
Tons of dlls (15 from the above list).
Application level (non-common assemblies and new assemblies) must reference many core dlls, which can be confusing) and tons of different namespaces are involved.
Deployment of said tons of dlls can get problematic (I sometimes use ILMerge to alleviate this and the above problems, but let's put that aside for now).
Open source project lifetime - open source projects come and go, so if any of these become no longer actively maintained, it can be concerning if there are internal bugs that need fixing or enhancements we want.
Obfuscation of "how to do things". We don't actively leverage every part of the above frameworks. In fact, several of these frameworks have overlap and provide redundant components and functionality. In terms of development, this can be confusing. We want a consistent implementation that is straightforward and easy to understand across our code base. Having multiple areas that do the same thing in different ways can be troublesome in this respect. This is probably one of my biggest concerns.
You're in big trouble if these frameworks reference different versions of other assemblies (ie. one internally references Unity 1.1 and another Unity 2.0).
The alternative? Include the source code in a common dll for your project(s) (ie. MyProject.Common). Let's put aside the issue of adherence to license requirements for the time being.
This has several negative implications too:
It's not as easy to leverage updates released by the framework's provider - you need to update your source code.
Encapsulation of functionality - it's easier to break this paradigm when the source code is all in your hands.
So, I know people probably have lots of opinions on this...and I'd like to hear them.
Thanks.
For some aspects of your problem, this might be relevant: http://en.wikipedia.org/wiki/DLL_hell#Running_Conflicting_DLLs_Simultaneously.
Another common solution to this problem is to write an encapsulation layer on top of the functionality needed, which at least protects your code from wild changes when upgrading to new versions of supporting libraries.
As to open source project lifetime, it should be clear which projects are healthy and which are not. For example, a project that is part of the Apache or Eclipse foundations are probably healthy, whereas some random thing on sourceforge is probably not. Generally, you can avoid this problem altogether by avoiding projects that do not seem active.
For the negatives to copying code into your project:
I know you wanted to put license aside, but you cannot in reality. I am not a lawyer and you should consult with one for your project if there may be issues, but if you are developing a proprietary system it could become GPL'ed accidentally.
It makes your development environment more cluttered. You have to worry about making sure the copied-in code ompiles properly, is being compiled with the right version, and has the right build scripts. You also have all this extra code in your IDE that takes up space.
As you pointed out, it makes updating code very difficult.
If you have to file bugs with the Open Source project, it becomes more difficult to do.
If you're not careful, a junior developer who doesn't know any better could go into the code and start mucking around with it.
There's probably more reasons not to do it, but that's a few. Hope that helps.
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 7 years ago.
Improve this question
How to successfully implement democratic (non-BDFL controlled) type of management for the open source project?
More specifically - for the project using distributed source repositories.
What style of communication is best to adopt in such environment?
How to encourage merging branches into the master?
I am mostly interested in establishing the situation where people can directly merge into the master branch under the "social contract" agreement that they follow the project roadmap (which they themselves help to define) and that code they commit is tested.
I specifically want to encourage workflow
define the problem->define requirements and specific metrics of success->architect->build and test
The reason is that - I often see emails like here is the problem and here is how I think it should be solved
Immediately somebody else jumps in and starts a fight.
Not productive at all.
Often disagreement of that kind stems from not being on the same page on the problem definition, requirements or architecture. Or sometimes just because nobody even thought about such things.
How to encourage people to analyze the problem properly, share great ideas and select the best solutions?
How to organize communication so to avoid silly fights, make good decisions without being overly bureaucratic and move along at a good pace ?
Would you have any suggestions? Are there examples of projects managed this way?
How do you think adoption of distributed revision control instead of centralized affects the style of project management?
edit: found some interesting links in related questions
http://gettingreal.37signals.com/toc.php
http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/
Sorry for this somewhat off-topic answer (i.e. one not addressing directly the question). Please edit at your heart's delight!
Projects _do_ need executive governance!
Such may come from a single Benevolent (or not) Dictator, or a [IMHO, small] group, possibly open, of diverse but like-minded individuals. A standard joke on this is that: "The group should be made of an odd number of members, and 3 is already too many"; in truth, small collegial committees can be very effective.
This requirement for a "non fully democratic" decision making entity is however somewhat aligned with the processes suggested in the question. To effectively harness the good will of contributors to the project, the executive team needs to
be perceived as legitimate
communicate effectively
empower "the masses" to contribute with roadmap definition, problem identification, solution scoping and all other design-level tasks. (All the while it remaining clear that in the end, and after all has been said, final decision will be done in committee.
DELIVER a good and vibrant product (BTW by adopting agile development processes, the time between deliveries is lessened)
compromise when needed
advocate the interest of pooling resources in a coordinated fashion, rather than branching out.
Share the glory!
To support all of this formal documentation and processes are very useful. For example, the define the problem->define requirements and specific metrics of success->architect->build procedure indicated in the question can be implemented in the form a single collaboratively edited document (wiki-based or other), i.e. one per issue/idea. This document is templated with a defined format: required attributes such as date, initial posting info... and sections which are opened (and closed) for editing following a given schedule. This allows keeping a clean(er) record of the way the collective though of a given issue, what was suggested etc, what was [authoritatively] decided and why.
With such a process, the community feels engaged and hopefully individuals not too disappointed when the eventual decisions do not go "their" way. They can read and comment on the what and why of the decisions.
Another useful approach is to reward effective participation by informally (or factually) provide more weight to the contributors who effectively help with the project. The more active members can either gain their way into the "inner circle" or be handed-out leadership roles on subsets of the project.
Finally, the leaders of a project (whether in the context of a "democratic" or of a "partially dicatorial" leadership) need to be ever vigilant about "peace keeping". Contributors to Open Source projects are typically energetic, smart and opinionated individuals; conflict of opinion, conflict of personalities, impatience etc. is to be expected. These clashes however can be eased by systematically addressing issues with clear facts, moderating/editing aggressively against name calling and non-productive forms etc.
Originally posted on MetaOptimize.
Constitution for Governance of Open-Source Projects (v20100227)
Let it be affirmed that the primary goal in instituting governance of an open-source project be to ensure the long-term health of the project.
Accordingly, the default bias should be towards openness and inclusiveness.
However, policy should be changed as issues present themselves, in order to maintain the long-term health of the project.
For the model of decision making, we favor a "do-ocracy".
The people who contribute the most generally command the respect of the community.
Alienating them is the best way to derail the project.
The repository should be open the committers, given that commits can easily be reverted and commit-access easily revoked. This is preferable to alienating potential committers.
To ensure transparency for developers new and old, and allow them to decide their involvement in a project based upon the history of the project, their should be transparency and openess in the inner working of the project. For example, the email archive should be public.
Lastly, let us remember that too much red-tape gets in the way of progress. So red-tape and other barriers to contribution should be avoided, and only added as issues present themselves.
This Constitution can and should be amended as issues present themselves.
Therefore be it resolved.
access to repository
there are several options ranging from one controlling committer to anyone can commit - but upon social agreement that they respect the project guidelines and the roadmap.
in my opinion distributed repository allows you to be more relaxed with who you allow to commit, because there are multiple backups and the repo becomes virtually unbreakable.
on a separate note - anyone can commit approach - which I would like to test out - sounds more like a "wiki". I can directly compare this with my experience managing a wiki (nmrwiki.org): where despite complete openness - where not even user registration is required to edit the resource, people are often wary about "breaking stuff" and this worry becomes a mental barrier to making a contribution. So a permissive approach to repository management may just work.
Communication style:
email and mailing lists:
discuss everything concerning the project in public (?)
when asking questions - do not bundle
questions with your own opinions
encourage people to propose more than one solution
ask people to weigh pros and cons
be brief and to the point
avoid frivolous language that can be perceived negatively with people that do not know you well
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.
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
After every new program written a lot of paper documentation remains.
Apart from the usual scribble notes from the programmers there usually is a nice heap of papers containing physical model explanations, calculations and so on (equations, tables, graphs, little pictures describing variables ...)
We usually do numerically intensive calculations in console applications, which are not released to the public (remain in the house, only results go out). Before each project is finished all those papers have to be packed somehow with the application, so that one day, when someone will be reusing parts of it, has some idea what is what in there.
So far, we've been using the 'dirty' solution of just scanning all of it, and packing it up on the disc with the application.
So I was wondering ... for all science guys here in a similar situation ... how do you handle project documentation which is needed, but not released to the public ?
(the one that does, goes to the dtp laddies, and they make it nice and shiny - not our problem anymore :)
I use one of three options:
Keep everything in my lab notebooks, which I archive myself, for low-level stuff
Scan the paper document, and add to source control in pdf. It's ugly, but if someone needs it, it's there
Transcribe the equations, results, etc... in a clean format (usually Latex) for future reference, and again, add to source control. Official paper copy gets signed (I work in a highly regulated domain) and filed in a binder.
In the projects I've worked on we have done a lot of physics calculations in our programs and consequently we have a lot of whiteboard sessions with equations we are working on.
We keep a wiki for each major project and after each whiteboard session we physically photograph the whiteboard with a digital camera and upload/organize it within the wiki. We also scan in paper documents from developers notebooks if it is important and include it in the wiki as well.
Then, we back up the wiki on disc for storage. So our solution is pretty similar to yours, other than we use the project wiki for organization.
If it's important, it seems to me you should treat the internal documentation with the same care with which you treat the public docs.
I create UI paper prototypes when designing the UI of an application, which produces lots of A3-sized papers (in one project we had many desks covered with papers). When the design is ready or it needs to be mailed to somebody, I take pictures of it with a digital camera, so that I can produce a series of pictures showing how to perform some tasks on the UI, which serves as documentation of how the application is meant to work. This serves also as a backup, in case somebody steals/cleans away the original papers.
Here is some of the thoughts... Not so practical though :)
We can make it part of our Check-in notes. This may help the developers going to maintain the application.
Update the requirement document/Low level design document with these items