Survey Results

First PrevNext

Documentation & UML Rocks in Visio Infinite_Loop29-Jun-02 4:05 Infinite_Loop 29-Jun-02 4:05  I currently doument all of my personal and work projects using the standard software design & specification style using UML. I found that Microsoft's Visio has a template library containing the vast majority of UML's required objects. These objects are drag-drop & attach to the desired location. This makes creating UML diagram to aid in documenting incredibly quick. The UML objects are incapsulated containers and can hold a great number of attributes, espcially in the case of the class object used for class architecture design diagrams. Visio is well worth the investment for any software programmer. Born 2 Code... UML synchronisation with the code? Franky Braem25-Jun-02 10:13 Franky Braem 25-Jun-02 10:13  I always start the design with class diagrams, sequence diagrams, ... But while I'm coding I see the need for another class, optimization or a new method and that is when my UML diagrams our getting out of sync. How do you handle this problem? I know there are some IDE's like Together where you can change your diagram and the change is reflected directly in the code. I also use Doxygen to document the code. Re: UML synchronisation with the code? Gary Wheeler26-Jun-02 2:37 Gary Wheeler 26-Jun-02 2:37  Tools like that seem to just move the programming effort one level up. You're not writing C++, you're writing UML that a UML 'compiler' converts into C++, that is in turned compiled. This is reminiscent of the heyday of Ada, where you essentially had to program to the meta-rules enforced by the environment, rather than the language itself. "Think of it as evolution in action." - 'Oath of Fealty' by Larry Niven and Jerry Pournelle Re: UML synchronisation with the code? S van Leent26-Jun-02 7:07 S van Leent 26-Jun-02 7:07  Yeah, my favorite UML Program: Together. Did you know that you can also do some reverse-engineering... So input the C++, and get the output in UML Sjoerd van Leent LPCSTR Dutch = "Double Dutch " documentation hell Brian van der Beek25-Jun-02 9:19 Brian van der Beek 25-Jun-02 9:19  In our project we're using Rational Rose to creat our design (in UML). Then we use Rational Soda to generate a word document that contains the Rose design, so we can add some additional proza. Of course these tools are crap, it takes for ages to make a decent layout and even longer to just generate a word document. On top of that we write doxygen style comment in our code, so we can generate html documentation. And all this has to be kept in sync. So you think you've got it hard, writting some comment in your code... ha ! Documentation depends on the audience Gary Wheeler25-Jun-02 5:33 Gary Wheeler 25-Jun-02 5:33  Documentation you write depends on the audience. When my group is starting a new project, we usually already know the roles we're going to play on the team. 'X' will do the GUI, 'Y' will do the sequencing component, 'Z' will write the drivers, etc. We usually end up writing one or more informal documents that describe how we're going to build our pieces and the interfaces between the pieces. These documents usually have block diagrams, are highly technical, and are intended for use within the team only. Documents for the outside world (marketing, service, and folks of that ilk) are usually more presentation style, with screen shots and simple, straightforward verbage. Documentation in source code, which is intended for other team members or future maintainers, is a different story. One of the very best ideas I ever got from a class instructor was from Dan Saks (secretary of the ANSI C++ committee at the time): "If you can say it in code, do so. Otherwise, say it in a comment." Source code, written properly, can always say 'what' you are doing, 'how' you are doing it, and even 'when' it should be done. Comments should be used for saying 'why'. Coding in this fashion should reduce the perceived burden in writing comments. Using this approach, I comment far less now than I used to, but I produce much more readable code. "Think of it as evolution in action." - 'Oath of Fealty' by Larry Niven and Jerry Pournelle Re: Documentation depends on the audience Chris Maunder25-Jun-02 16:41 Chris Maunder 25-Jun-02 16:41  Gary Wheeler wrote: If you can say it in code, do so. Otherwise, say it in a comment. Nice. I find I tend to use verbose names for functions and variables and only comment to either give a quick overview of what a function will achieve or explain a sequence that may be a little counter intuitive (ie for optimisation or bug workarounds) cheers, Chris Maunder Rub your belly and pat your head simultaneously. Sometimes that helps me make sense of things - Jon Sagara Re: Documentation depends on the audience Gary Wheeler26-Jun-02 2:34 Gary Wheeler 26-Jun-02 2:34  That's exactly it. Dan's point to us was that you should use comments to say the things that the code can't. I'm another one for using verbose names, and with the advent of tools like IntelliSense/Visual Assist, there is very little excuse for not using them. I'll use short names for locals (plenty of i's, j's, and k's ), but that's about it. "Think of it as evolution in action." - 'Oath of Fealty' by Larry Niven and Jerry Pournelle Doxygen Stephane Routelous25-Jun-02 2:29 Stephane Routelous 25-Jun-02 2:29  For generating the class documentation, I'm using doxygen ( http://www.doxygen.org ). It is really a very cool programm, and free ! Stephane www.exotk.org Documentation! We don't need no f'ing documentation! Roger Allen24-Jun-02 6:18 Roger Allen 24-Jun-02 6:18  Of course we do. We just do it in computer geek speak! Actually, its something we are driving hard at here now. As for commenting, its always something I have done liberally due to coming from a core assembly programming background where it was required so much or your lost a week later when reviewing the code! Roger Allen Sonork 100.10016 If I had a quote, it would be a very good one. Soon will go to UML Navin24-Jun-02 2:13 Navin 24-Jun-02 2:13  Right now, it's sporadic comments and some documentation here and there. But we are redesigning a huge chunk of our code, and figured this is the time to do it right. If we tried to do any kind of UML or diagrams for the design of our code, it would look like a nice plate of spaghetti. Even if you win the rat race, you're still a rat. You got to differentiate Daniel 'Tak' M.23-Jun-02 22:13 Daniel 'Tak' M. 23-Jun-02 22:13  I know a lot of people who really comment every second line of code (best example: "int i = 0; //declare variable i of type int with default value 0"). Or they waste weeks for writing a complete documentation. You have to differentiate here: will the source-code ever be used by someone else? Furthermore, will it ever be used by someone who cannot ask you directly? If there are no people who will ever read your code, why waste time and write complete books of comments? One argument is that reading your own code after several years once again becomes easier with comments - but be honest, YOU wrote it, YOU will understand it even after some years. Comments are just overestimated. If your code, on the other hand, is read by many people comments are a must (or do you want to answer about 2,194 million questions each day?). For me, commenting is a big pain in the ass Re: You got to differentiate Michael P Butler23-Jun-02 23:42 Michael P Butler 23-Jun-02 23:42  Tak wrote: One argument is that reading your own code after several years once again becomes easier with comments - but be honest, YOU wrote it, YOU will understand it even after some years. Comments are just overestimated. Comments are very important when going back to old code. It saves time in getting up to speed on code you'd written years ago. The number of times I've had to go back to code written four years ago and cursed myself for not adding comments. Comments don't need to say what the code does, it is more important to say why it does what it does. Tak wrote: Or they waste weeks for writing a complete documentation. Documentation is only a waste if it is never updated. Michael Logic, my dear Zoe, merely enables one to be wrong with authority. - The Doctor Re: You got to differentiate Navin24-Jun-02 2:11 Navin 24-Jun-02 2:11  Tak wrote: You have to differentiate here: will the source-code ever be used by someone else? Furthermore, will it ever be used by someone who cannot ask you directly? You should always assume that YES, somebody else will use it. What happens when you take that big management promotion at another location? Or if you switch companies? OR even if you start working on new code and don't touch the original code for years, and somebody else has to maintain it? Even if you win the rat race, you're still a rat. Re: You got to differentiate Elrond24-Jun-02 5:01 Elrond 24-Jun-02 5:01  Actually, for most professionnals, you have to assume that people will have to get in your code without having the possibility to ask you. It can be because after sometime you won't be in the company anymore, or working in another site or because you are in holidays . The only case you may not have to comment your code is for projects you do for yourself. And even then, it is much easier to come back into it of there are comment. I agree that usually you will be able to come back into it even without comment, but it will be much longer. And if you come back into it after several years, you may even not be able to understand, as your way of coding will have changed. When you look at your old code you sometimes realise how bad it might have been By the way, I agree that commenting is usually a pain but it still has to be done. And if I don't, my company will probably fire me, and they would be right! Computers have enabled people to make more mistakes faster than almost any invention in history, with the possible exception of tequila and hand guns. - Carl Gundlach Re: You got to differentiate bishbosh0228-Jun-02 4:06 bishbosh02 28-Jun-02 4:06  I have had to look at someone elses code to fix a bug after they had left the company, one function was 20 pages long and know comments, it mad my head sore...................... UML is the only way to go. Martin Marvinski23-Jun-02 19:36 Martin Marvinski 23-Jun-02 19:36  When I'm charging money, everything is well documented and planed, so I obviously know that UML is the only way. Re: UML is the only way to go. Nnamdi Onyeyiri24-Jun-02 1:59 Nnamdi Onyeyiri 24-Jun-02 1:59  what does UML stand for? Email: theeclypse@hotmail.com   URL: http://www.onyeyiri.co.uk "What goes up must come down. Ask any system administrator" Re: UML is the only way to go. SimonS24-Jun-02 2:38 SimonS 24-Jun-02 2:38  UML = Unified Modeling Language. Cheers, Simon "Sign up for a chance to be among the first to experience the wrath of the gods.", Microsoft's home page (24/06/2002) Re: UML is the only way to go. David Wulff24-Jun-02 3:21 David Wulff 24-Jun-02 3:21  I disagree with Simon, I always thought: UML = Unecessary Management Language ____________________ David Wulff Neil says: dave i am a homosexual and i am in love with your father Dave says: That's okay son, eighteen years ago I was in love with your mother. Re: UML is the only way to go. Nemanja Trifunovic24-Jun-02 5:02 Nemanja Trifunovic 24-Jun-02 5:02  Anybody knows a good UML tool? I've tried Rational Rose and MS Visio but I don't like them. I vote pro drink Re: UML is the only way to go. Ed K26-Jun-02 3:59 Ed K 26-Jun-02 3:59  http://www.sparxsystems.com.au/ ed Someday we'll look back on this moment and plow into a parked car. Evan Davis Scribbles ColinDavies23-Jun-02 18:35 ColinDavies 23-Jun-02 18:35  I use lots of paper in the planning stages of my personal projects. And thus I'd be just repeating myself to formalize it. Although I'm now reviewing projects and adding green stuff. I have thought about scanning my scribbles but it seems like too much work. Regardz Colin J Davies Sonork ID 100.9197:Colin More about me Re: Scribbles Daniel Ferguson23-Jun-02 18:56 Daniel Ferguson 23-Jun-02 18:56  When I'm working, I find it very helpful to have scrap paper to draw sketches and write notes. This is something that I find very difficult to do with a computer. There's an idea for a killer app: use a pen and tablet for input and let the user sketch, erase and link different bits together. "The lives of these people are contingent on events; if things stop happening to them they will stop being." Re: Scribbles ColinDavies23-Jun-02 19:07 ColinDavies 23-Jun-02 19:07  Daniel Ferguson wrote: There's an idea for a killer app: use a pen and tablet for input and let the user sketch, erase and link different bits together. That makes sense, although I have never worked with a tablet. I find notepad an essential app as it is. Regardz Colin J Davies Sonork ID 100.9197:Colin More about me

Last Visit: 31-Dec-99 18:00     Last Update: 21-May-24 4:54 Refresh 12 Next ᐅ

General    News    Suggestion    Question    Bug    Answer    Joke    Praise    Rant    Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.