NICE! use cases! hooray!
Er... did you miss this post on page 2? :-D
I've written another introductory document that is meant to be oriented to non-technical users. I want to capture the interest of people that don't know what 'scenegraph' or even 'java' means. It's organized as a collection of informal use cases... I think a lot of people might find it interesting:
software documents are always evolving... and no one EVER has done something right the first time and succeeded
I don't know if I've mentioned that this is my third project in this area; I've failed twice. Actually, the other two were more of a 'proof of concept' and then a 'prototype'; now I know what I'm doing. :-D That's why the focus on extensibility now, you know how prototypes are, never extensible, hack it together ASAP.
Anyway, I wanted to mention that I got registered for a Java.net project. I've moved the homepage over, but I don't think its completely up to date. I haven't decided whether to stick with them or with my university for web hosting and CVS.
Every bleeping way I bleeping turn, there's another bleeping decision to make.
Dusty
]]>why is it when people mention diagrams/uml, and requirements, they start talking about the waterfall method? These things aren't synonymous.
thank you.
seriously, has anyone here used the waterfall method since like 1980? (exagerated rhetoric, please don't answer )
software documents are always evolving... and no one EVER has done something right the first time and succeeded
]]>Maven (another tool )
I heard about that before you mentioned it. I must be getting better. Actually, it was on the Groovy page, so you still get credit...
I haven't investigated it, but I think I'll stick with ant. The main reason is I'm already going to be learning too much new stuff to finish this in the four months I've allocated... (Call me nuts, but I'm an insanely fast coder. yeah. for sure. I can fly too, did I ever mention that?)
Dusty
]]>I've made my choice on design; I want to have a not too detailed physical design outlining the major classes (not all classes). I probably wouldn't do this if it wasn't a school project, but I was taught to design stuff, after all.
UML is fully object oriented. I just can't think in it. It's not that I don't understand the language; I just have to do a lot of translating in my head and that doesn't work too well when you're thinking. Think of the stories of blind people suddenly getting their sight and all they see is a bunch of colours, they don't understand the concept of 'shapes'. I know what 'shapes' are, but my mind doesn't 'think in shapes'.
I want to finish the physical design today (but I wont, I feel like shit and I got a late start, so I'll bust my ass all weekend to start coding Monday).
I have to say that the open source projects that you guys describe that don't use a formal design... they work pretty good in spite of themselves, eh? catb.org.
So, I'll have that design up for you're critique ("it's not detailed enough!", "translate it into UML"... :-D) sometime this weekend.
Dusty
]]>iterative model? Extreme? Rupp? TestDriven (I like this one too, but to make tests, you need requirements to test against)....
blech...Enough post hijacking...
We can talk about software development methodologies until we are blue in the face in another thread. Lets try to leave some semblance of Dusty's thread on Ensmer in tact..
(after giving up on Jython and deciding on Groovy -- wdemoss, where do you hear about this cool stuff?)
I hacked into dp's computer and stole his bookmarks.
About the design stuff, I generally perfer test driven development (a close approximation of it any way) and a continuosly evolving design over a formal water-fall methodology. Test driven development generally leads to writting only what you need, not over-engineering anything, and maintainable code. Beside, there is no better documentation then well written unit test. Maven (another tool ) has a really cool report it generates that is alot like javadoc but has the junit test cases that are browsable. If you have clearly written test classes and methods this can be much better form of documentation then javadoc / uml / rose diagrams. At least IMHO.
-wd
]]>The stuff I wrote yesterday for the InputManager (after giving up on diagramming. It just doesn't work for me!) would make less sense to you than the code.
maybe, but think about it this way - Joe Schmoe knows jack-sh*t about java syntax or even OO in general... he wants to reproduce something you did in perl (don't ask - it's my example, I'll do what i want!) and looks at your code and the javadoc and gains almost nothing except the @param descriptions (along with a functional description). He now has no idea where this falls in the grand scheme of things and basically has to waste a bunch of time learning java and referencing a book to reporduce your code. Yeah it's not hard, but you have to understand, you won't always be using java and you won't always have javadoc... in 200X java may be defunct and not used anymore and if someone wants to reporduce yuor stuff he's going to have to learn outdated coding techniques to figure out what you did.
I alao look at my older code and think 'gee, I was a real moron programmer back then, what am I gonna think of my current skills in two years?'
We all do that, heh....
I know a lot about having a good design... I just tend to like to design in code! hehehehe
yeah, but the real point of UML and all these other lame techniques is this - it makes everyone able to design the same way if needed, so people can communicate.... i design in almost all pictures and flow charts... what if you and I were working on the same project.... you'd send me some pseudo code to look at your chunk and i'd send you some diagrams - we'd both be confused as hell.
I'll be heading back into a (text based) physical OO design after I finish this. I just needed the sleep last night, lol.
that works too.... text based, picture based, whatever....
it would have been better if they'de documented the files, but the design... I dunno.
well, if there was a design doc, you could have easilly found the portion that described what you needed and it should have listed function names and files - making your searching job much easier... if the files were commented, you would still have to find which file(s) to edit by reading through them.
as far as documentation being crappy and not up to date.... I agree. but this is namely on open source projects..... there was a big schpiel a while back by some guy saying that open source programmers know nothing of standard software engineering practices - most just jump in and start coding... this makes it hard for companies newly moving to OSS to hire programmers - they have their methods and practices, and the open source programmers just want to ignore them and start coding - no design, no documentation, nothing - "submit a patch later if its not good" - I am strong believer that the OS community really needs to learn standard practices... even if they are commonly used under MS technologies.
I must state, for the record, that I find it tedious and boring as well - it's terrible spending weeks writing up a document and busing out rational rose diagrams.... but it pays off in the end.
]]>Maybe its just the diagramming that's frustrating me.
If you don't like diagramming or documenting in advance before coding, keep a logbook.... what you have done and what to do next. No need to keep everything in your head and also helps to make the documentation once ready. For other developers to join, its good to categorize the logbook in sections.
]]>I don't know about you but I don't want to read through 100 pages of code... I'd rather read a few pages written in english to understand something.
To be honest, the code often makes more sense to me, and the english docs are ALWAYS out of date. I do make extensive use of javadoc comments (or equivalent in other languages); I figure that's all the documentation needed. Further, it makes more sense to me to document the code after its been written, but that might just be a bassackwards way of looking at it.
It's also easier to diagnose bugs this way...
again, that's assuming the docs describe the code; the code, I've noticed, is usually different from design docs.
The thing about documenting this stuff is this: write it out however you want, and however you understand it
Yeah, but then you can't exactly publish it. The stuff I wrote yesterday for the InputManager (after giving up on diagramming. It just doesn't work for me!) would make less sense to you than the code.
Also, try this - find a fairly large project that you did, say 2 or 3 years ago.... and go back and look at it.... you'll probably be confused... I've said many a times "why the hell did I do that?" while looking at older code.
Yeah, I've done that exercise... that's why I usually put in Javadoc comments that are longer than the actual methods nowadays. :-D
I also look at my older code and think 'gee, I was a real moron programmer back then, what am I gonna think of my current skills in two years?'
i remember when I thought it was worthless....
I don't think its worthless. This isn't my first big project or my first open source one (it's my first big open source project where I'm head developer). I know a lot about having a good design... I just tend to like to design in code! hehehehe
Actually, its the diagramming I've decided is worthless, but only because of my spazzed out thought processes that are unable to interpret shapes or something like that...
keep in mind, this is just my 2 cents based on things I've run into...
I'm not discarding your advice; I'm just... complaining about how much work it is. :-D I'll be heading back into a (text based) physical OO design after I finish this. I just needed the sleep last night, lol.
I actually think the best way to understand something like this is to have to pickup on a fairly large project that has NO documentation.... it's a painful process....
I remember trying to hack the readline library... and its not even that big, and its got decent inline comments... but I did have to search through a half dozen files before I could find the one I wanted to edit, then I had to search through the C code line by line and edit several of them...
it would have been better if they'de documented the files, but the design... I dunno.
Dusty
]]>It's also easier to diagnose bugs this way... i go "hmmm ok it's failing on download... let's look at what calls the download methods... oh these arrows show me exactly what calls it and what it calls... I didn't have to grep through a bunch of files to find this out....and look, this document has a granular list of what certain methods do... ok well based on the descriptions, the problem is function A... which according to the docs is in file A.java at line 123... it's go time"
for small projects which are common to CS classes (make a program which uses a linked list to do X and then transforms it to a red black tree and performs Y) they do only one thing and documentation is a waste.
The thing about documenting this stuff is this: write it out however you want, and however you understand it - don't worry about if the format is right or you document things correctly or use proper UML.... write it out how you see it. Just write down something which isn't code.... write down code flow... in whatever form you want (first I hit X and then I do this and then this happens or int X(char *c) --> double something(struct blah b) --> connect to google.com) just have something that someone can look at which isn't code.
When you do a project yourself, you know everything that's going on and it's easy to understand.... however, for others it's not so easy. Also, try this - find a fairly large project that you did, say 2 or 3 years ago.... and go back and look at it.... you'll probably be confused... I've said many a times "why the hell did I do that?" while looking at older code.
the key point is this: don't worry about formats or structures for documentation, just document something, anything.... even if it's bad and not even complete sentences.... hell when sequence diagramming is required, i don't even do it until the end... i leave the format like this:
int foo() calls
double bar() calls
char *func() calls
struct bigint *get_a_big_num()
i remember when I thought it was worthless.... but think of it this way: for a project like ensmer which is obviously a big undertaking, how is someone like me supposed to understand what's happening when your done... I'll take one look at the 300 java files and go "nope, sorry"...
keep in mind, this is just my 2 cents based on things I've run into... I actually think the best way to understand something like this is to have to pickup on a fairly large project that has NO documentation.... it's a painful process....
]]>I've spent most of the afternoon and evening (after giving up on Jython and deciding on Groovy -- wdemoss, where do you hear about this cool stuff?) working on DBUMLwPP (Dusty's Bastardized UML with Pencil and Paper) class diagrams for the project. I'm not sure if they've helped much, I guess parts of the design are solidifying. At first it seemed useful, maybe, but now it feels like a waste of time and I want to do my traditional CS project thing and start coding. It's worked before... only before I wasn't worried about having the result be extensible.
Maybe its just the diagramming that's frustrating me. I just don't think in pictures, and these diagrams look more like spiders than information to me, even though I'm drawing them myself and know what I'm thinking.
Actually, the clearest diagram is the one I got after I typed up exactly what the classes would do. I think I'll switch to a more verbose form of design, maybe with pseudocode. Something more suitable for me, lol.
So that's my rant. Somebody explain to me why I'm doing exactly one CS project now and I'm spending more time on it than I did doing six CS courses (including two projects...). I think its the open source thing, all of a sudden more than just my prof will know if I do it wrong.
Sucks too, cause I've always gotten good enough grades doing it my way.
Dusty
]]>