|
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...
|
|
|
|
|
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.
|
|
|
|
|
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
|
|
|
|
|
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 "
|
|
|
|
|
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 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
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
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.
|
|
|
|
|
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.
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
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.
|
|
|
|
|
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
|
|
|
|
|
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......................
|
|
|
|
|
When I'm charging money, everything is well documented and planed, so I obviously know that UML is the only way.
|
|
|
|
|
|
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)
|
|
|
|
|
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.
|
|
|
|
|
Anybody knows a good UML tool? I've tried Rational Rose and MS Visio but I don't like them.
I vote pro drink
|
|
|
|
|
http://www.sparxsystems.com.au/
ed
Someday we'll look back on this moment and plow into a parked car.
Evan Davis
|
|
|
|
|
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
|
|
|
|
|
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."
|
|
|
|
|
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
|
|
|
|