   Losing the big picture while coding
  I have the problem that I often lose the big picture of my program structure while coding. The best solution would naturally be to draw diagrams. I believe especially sequence diagrams would be useful, since my programs (usually games) tend to have complicated sequences and subsystem interactions. Until now, I've simply left some notes about the structure as comments in the code itself, but these are not practical, since you need to browse through the code to find them.However, when I try to draw such diagrams, it takes way too much time, and it's too time consuming to change the diagrams when the code changes.My question is, how do you solve this problem? How do you maintain the big picture of your code structure while coding? Which tools do you use to draw diagrams? Which diagram types do you use? How do you keep all your diagrams organized so that you can cross-reference them easily? How do you keep your diagrams up to date when the code changes?   
  Do you know what you are doing in the first place?Although anyhting I spend half an hour drawing tends to change immediately I get to actual coding part, designing your system and thinking it out thoroughly should help out a bit.If you know what you are building, you really should not lose the focus as easily as if you just came up with the stuff as you go.Well defined interfaces between subsystems also tend to encourage better structuring of your program.Whenever I draw pictures, they tend to be on very "high level" and contain large scale architectural decisions instead of trying to design stuff even on class level. That stuff tends to just get too volatile as I go on. I prefer few "important" pictures to a bunch of obsolete schemes that I have been too busy to maintain.Visual Paradigm has been a quite nice tool on UML / Use-case diagrams but it contains a heap more for pretty much everyone. From engineers to business men.   ;  Usually when I draw diagrams, I do it on pencil and paper. It's just easier to work with, an easier format to think in. First a rough draft with scribbles and stuff scratched out, then I redraw it in a reasonably neat form if necessary.They don't have to be pretty. For me, the act of drawing it out usually cements it in my memory. And if you do have to go back to it, you'll usually remember what you were thinking then, even if it's not perfectly clear.   ;Quote:How do you maintain the big picture of your code structure while coding?I don't. Keeping details in your head gets harder as you get older, and even mildly complex programs are too complex to hold all the details in mind. Abstraction is your friend. While coding, you should only need to be aware of the things directly relevant to that code.Having a good design helps. Having good intellisense helps a lot. Having consistent naming and coding patterns help.   ;  Ideally, you would have the entire design document of the application you are coding. The complete description of every functionality required. And the development divided in stages that are done when you code, test and debug the last routine in each one. That way you will always know where you are, what to do and how much is left to be done.   ;Quote:Original post by TelastynQuote:How do you maintain the big picture of your code structure while coding?I don't. Keeping details in your head gets harder as you get older, and even mildly complex programs are too complex to hold all the details in mind. Abstraction is your friend. While coding, you should only need to be aware of the things directly relevant to that code.Having a good design helps. Having good intellisense helps a lot. Having consistent naming and coding patterns help.Of course, in an ideal world your code is written so clearly that you don't need diagrams, or even comments. But we do not live in an ideal world. Like you say, abstraction is important. Aren't diagrams just that - useful abstractions?Since I'm writing a relatively large game in my free time (with long breaks between), what I need most is a quick way to refresh my memory about my program's architecture, interactions, sequences, etc. Doing this by reading my code is a pain, since it's a lot to read, and admittedly the code is often unclear and hard to grasp. (In an ideal world, I would refactor it and make it clear, but I have found that perfectionistic refactoring is rarely a good idea, since it takes way too much time. Besides, when I add new features, the new code will again be bad, so I there will always be unclear code in my project anyway.) Diagrams would be the perfect solutions for this, since they allow to understand the structure at one glance. But until now my attempts at creating useful diagrams have been unsuccesful, and I'm not sure how I can learn this. Watching how professionals do this would be very educational, but I don't have this opportunity in real life. Are there some online material or books available about this?   ;Quote:Original post by owlIdeally, you would have the entire design document of the application you are coding. The complete description of every functionality required. And the development divided in stages that are done when you code, test and debug the last routine in each one. That way you will always know where you are, what to do and how much is left to be done.I have found that designing everything in advance is a waste of time in my situation. Perhaps it works for professionals who have done everything already a million times, and know what works and what is doable. But for someone who is still learning, it is impossible to find a good design before seeing how the program develops. Especially in a game project, where it's very hard to predict what is going to be fun and what is not.;Quote:Aren't diagrams just that - useful abstractions?Not in my experience. They quickly go out of date, don't show actual interaction between portions of code, and generally aren't accurate or useful abstractions.Auto-generated database diagrams are useful to get a larger picture, but that's mostly because they can be automated, and interactions between tables are relatively simple and well known.Quote:Of course, in an ideal world your code is written so clearly that you don't need diagrams, or even comments. But we do not live in an ideal world.No, even in the real world you're better off with fewer diagrams and comments in favor of better names, better abstractions, and a better IDE.   ;Quote:Original post by TelastynNot in my experience. They quickly go out of date, don't show actual interaction between portions of code, and generally aren't accurate or useful abstractions.Let's say you have a large project, and you have not been developing it for several months. You have forgotten much of its architecture and how it works. What is the first thing you do in this situation? Do you simply read through all the relevant code files? Isn't that too many files to read? How many files do you have to read in average to get a good grasp? Do you use any additional tools at all to help refresh your memory?   ;Quote:Original post by formalproofQuote:Original post by TelastynNot in my experience. They quickly go out of date, don't show actual interaction between portions of code, and generally aren't accurate or useful abstractions.Let's say you have a large project, and you have not been developing it for several months. You have forgotten much of its architecture and how it works. What is the first thing you do in this situation? Open the solution, browse the solution layout. That's a good help. Then I'll usually run the app. Where/how it breaks is a good indication of where I left off. If it works, then I can look to see what I need/want to work on next.It usually takes about 2 hours for every 3 months the project has been on ice (assuming I've been using the language it was written during the mean time).Quote:Do you use any additional tools at all to help refresh your memory?Not really, but I also don't totally forget how things work anymore (generally). I might forget where some things are, or what they're exactly named, but following language idioms means I have a good grasp of how they work (because everything works similarly from project to project) and where to find things.Abstraction and consistency are your friends.   