Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

How should I document my designing of the app better so that I avoid programming by coincidence? How can I structure notes so that it is clear how an app works so that when I refer to it a year later I'm not lost for the first 3 days?

share|improve this question

closed as too broad by gnat, MichaelT, Dan Pichelman, GlenH7, Jonathan Eunice Dec 10 '14 at 19:08

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

That's what I am asking, how do I organize my thoughts on paper or in notepad so that I am making the most of my time by not only allowing myself to think about the problem but also creating something I can refer to usefully. – davidahines Sep 21 '11 at 16:53
I believe it is, I don't want to pidgin-hole them into talking about pen and paper notes, if someone says, use a UML diagramming application and makes a reasonable argument, I would like to explore that as well. – davidahines Sep 21 '11 at 17:23
You may consider using mind maps to organize your notes, at least in the initial (analysis) phase. – Péter Török Sep 21 '11 at 17:26
@dah: "pigeon-hole" it's a bird's nest. "pen and paper notes, if someone says, use a UML diagramming application " are all technologies to implement some goal. What's your goal? Given a goal, we can pick technologies. With no goal, nothing good can happen. Please define your goal, objective, end-game or outcome. – S.Lott Sep 21 '11 at 17:28
up vote 1 down vote accepted

Separate the Analysis from the Design. Don't let architectural issues intrude on the requirements. Take your notes from an outsider's perspective, what will they see and where does that data come from?

You should spend more time on your notes, not less. You can't create the architecture to fit partial notes, that's like designing clothes for a mannequin missing both legs and an arm, sure it's fast but (as you've noticed) it's hardly functional ;-)

Read up a little on UML, even if you don't use it to sketch out your app the methodologies that use UML will provide you with inspiration.

share|improve this answer
This is interesting, I know basic uml but I find it kind of hard to recall all of the particular symbols when referring to relationships. – davidahines Sep 21 '11 at 17:26

Applications consist of at least two major sets of requirements: Business and Technical. Business Requirements come first and should describe what the application needs to do and the business goals it will solve. Having a good set of Business Requirements often requires not only understanding what the user asks for, but also what the user really wants. I mean, a non-technical person often cannot express bus. req's clearly and fully without the help of a qualified BA (one that understands the particular Business at hand).

Assuming you are a qualified BA and you have a complete set of Bus. Req's. Then you need to drawup a plan to build the product, technical requirements. There are many paradigms and approaches to managing a project. You should pick one that works for you and the team, say Agile.

I recommend drawing out the Entities required to solve the Business Requirements. Then, take a divide and conquer approach to implementation. Red-Green refactor works quite well for division of labor.

For example, an Employee is an Entity in your product. The Employee needs CRUD operations. Create an CRUD interface, and a unit test for each of the 4 CRUD elements. The unit tests all fail at the start. Then, delegate a programmer to implement the CRUD operations of the Employee entity until they all pass.

Rinse and repeat. Assuming you have properly identified all entities, this will bring you well into the last phases of back-end development. Add helper classes and a common library, keep unit tests updated and over time the products will improve and development will be faster.

Finally, decouple front end work from backend by using Inversion of Control. Do up your CSS and all that jazz with mock data until complete. Then, plugin the backend.

That's how I like to do things at least. Keep in mind, there are no "right ways to build a bridge" in software. Each team is unique. Each project is unique. Paradigms and standards are guidelines set by developers who solved particular problems in a particular way and said solutions stood the test of time.

Good luck.

share|improve this answer
What does BA stand for in this context? Business architect? – user937146 Sep 21 '11 at 19:29
@user937146 - Business Analyst. – P.Brian.Mackey Sep 21 '11 at 19:54
Ah, makes sense. Thanks! – user937146 Sep 21 '11 at 20:59

Bear in mind that my answer reflects my strengths and weaknesses, which may not be yours.

I divide programming into three parts 1) syntax (defining variables, read-write operations, etc.), 2) computations, and 3) logic.

My big weakness is in the math/computation part, so I try to get help on that from others. Specifically, I will try to get the user, typically an engineer, to write out all the relevant equations and computational formulas for me. Absent such help, I may consult a textbook, or use a programming library.

My strength is in languages, so I tackle the syntactical issues on my own: variable definition, formatting, layout, etc. This is much easier, if I've followed step 1 and had the engineer define the problem for me.

The last area is logic: branching, loops, links, test conditions etc. This is my area of intermediate difficulty, which is why I tackle it last.

This advice may not work for you in its exact form. But the idea is to identify your strengths and weaknesses, and get any help you need in the latter area.

share|improve this answer
This is a helpful response, how do you put this into a form that you can refer to? Do you write paper notes, use UML, some kind of TODO list application? – davidahines Sep 21 '11 at 17:25

If you're not good at note taking (and it sounds like you're not) then I would try prototyping. Sketch out a rough plan then spend a couple of hours to see if it's a good idea. You can then use the prototype as a plan of how your production should work. (do a rewrite)

share|improve this answer
Thanks for your response, Tom. I agree that I take poor notes, how do I improve that? Do you mean paper prototyping or mockups or UML? – davidahines Sep 21 '11 at 16:54
I mean actual code prototypes. Have a look at the pragmatic programmer – Tom Squires Sep 21 '11 at 16:57
I think I'm going to buy this book, it looks promising. – davidahines Sep 21 '11 at 17:23

I make notes but they're not very useful, how should I organize my notes[...]?

You need a bug tracker.

If you want to start a project, report it's Elevator Pitch as a bug! Attach each important feature to support that goal as another bug.

If you've got written notes, either ideas you've brainstormed, or minutes you've taken from a meeting with a customer, those need to make it into the bug tracker as soon as possible.

The value of organizing your project plan in this way is that you can easily search and organize each task according to how it relates to other items, how urgent it is, how much you've completed. It also allows you to link the changes in the source code back to the factors that influenced them; this change fixes that bug or implements that feature.

share|improve this answer

You can use a class diagram for documentation purposes. I don't mean to generate an automatic documentation using UML which is really crap but to create manually class diagrams views of your packages.

You don't really need to know UML because if you reverse your project then you get your model and a class diagram for each package. You then just add notes on classes and methods. You save your diagram directly at the root of your package. Job done !!

Really easy and very efficient. This is what I do and developers love me :-)

share|improve this answer

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