Software Documentation | The Coffeehouse

zhuo

ScanIAm wrote:
Sven Groot wrote:

Sampy wrote: Comments in code? You mean unit tests?

Please don't tell me you believe unit tests are an adequate replacement for comments. I once inherited a project whose original developers believed that. It was an extremely well developed application that followed XP coding practices to the letter, but it was still hell to get a grip on it due to the lack of comments. I ended up spending an afternoon with one of the original developers to really understand the code.

Even if your project is really well designed, uses clear, consistent and consise identifiers and easily readable formatting, and has unit tests for everything, you still need comments!

Sorry, Sampy, I gotta agree with Sven on this one. I'm sure I'm "Doing it wrong"* but even with the simplest tests, it may show you how to do something, but not why you would want to. I still think the /// comments at the top are cool and in some of the trickier areas, I'll comment each line.

Partially, because the wonders of "Refactor..." make it so that any joker with some free time can change the names that you've carefully chosen for clarity. Comments make it so you can at least figure out what you meant.

I love testing, though. It gives you that mid-project satisfaction that you didn't completely screw up. Sometimes you didn't know that for weeks

*I'm on a couple of these lists, and I cannot tell you how annoying it is to hear "Well, of course it failed, you did it wrong" as a response to any and all failed XP/Agile/TDD/scrum/whatever attempts. If the process is that difficult, natural laziness is going to keep it from ever reaching the mainstream. Or, maybe some of these practices need reexamination.

Not to go off topic on my own topic. I will start a new thread on software testing.

ScanIAm
On a scale of 1 to 10, people are stupid.

irascian wrote:

Manip wrote:

erik_ wrote: Btw. how do they do this with opensource software? Do they for instance also create a requirements specification and lot's of uml diagrams, but keep that to themselves?

lol... Most OSS projects have NO documentation... The ones that do are the exception.

Tell me about it. Even the "big hitters" typically point you at a crappy Wiki which has little useful info on it or (in the case of NDoc - shame on you!) is a link that gives an error.

And if there is documentation the assumption is ALWAYS that you're from the MTV generation and suffer from Attention Deficit Disorder so that the only way to read documentation is on screen.

Don't get me started on how hopeless the chm format is for printing stuff that can be read on a commute!

One decent documented OSS app is NUnit. It's clear and concise and took me about 20 minutes to figure out 95% of what I'd ever want to do with it.

ScottWelker

erik_ wrote:

Kryptos wrote:
So here's my questions what is the best way to learn a method of coding, I see here that some people to UML, What is that? Is there a coding method or methods that should be followed?

I am not sure if I have enough knowledge to explain this correctly, but here it goes: ...

I think you did a good job, and I'd like to add more but, as noted, it's off topic Sad

Check out Dean Leffingwell's Managing Software Requirements: A Unified Approach - but remember it's not gospel, just a collection of good tools an technicques that may be helpful - depending on your needs. Geez! I couldn't help myself Perplexed

j0217995

As someone who writes documentation for Ubuntu/Kubuntu and also has worked on The Official Ubuntu book, I would agree that documentation is the most often forgotten part of a project. Too many times the developers of a project will put in shiny new app X and then forget to update those who write the documentation that shiny new app X is now the default app and needs to be used. (Change app to feature and you have the same problem)

One of the great things about the Ubuntu/Kubuntu/etc world is the hard freezes that go into effect that allow people to create/change/modify the documentation before the release. Then the documentation is frozen for translators. While it often times provides for a great flurry of commits at the end, the freezes strive to solve the problem of shiny app X sneaking in at the end.

I would echo someone's else thought that Open Source software has some of the worst documentation (if any documentation) out there. People volunteer to create something new, not document something new. THere are some great examples of Open Source documentation (GNOME, KDE, Gentoo) but a greater number of terribly documentated products.

Jonathan

SaraJoRedux
GirlDeveloper.com

I hate documentation. Especially the kind with screen shots. I hope to go through my entire career with comments in my code being enough for someone else to write documentation.

Please, god.

erik_
Tablet Power

That sounds like user documentation Big Smile

Documentation of knowledge is very very usefull if you need to continue a project from someone else or start a new one, finish and modify it a year later. Good requirements is a must have. Questionable is if you are the one to create them or if the shop is large enough to have a person around to perform this tasks. I feel more and more that I need that knowledge on paper, because it now comes back as bugs and needs to get solved asap while I am working on something else. The only real problem is that documentation takes time upfront, while the problems from not having documentation is time afterwards and not visible.

Comments in code aren't always good, good comments in code are.
I've seen this extreme commenting pratice, which is not helpfull in any way. The code is full of stuff like this:

// Close the stream
writer.Close();

Next to the extra space it takes, and all the green lines in the code it is also not very good if you refactor a lot. If I use VS refactor/rename for example, it will not modify any comments. You will end up with comments saying this does X while it actually does Y.

Bas
It finds lightbulbs.

erik_ wrote:

// Close the stream
writer.Close();

That's my major peeve with overzealous commenting. In school I was taught to comment everything, which is the dumbest idea ever, but I'm guessing they just said that because after a while you'd just give up and comment some of your stuff, which is still better than nothing at all.

Like with everything, Code Complete has a bunch of pages devoted to some documenting wisdom. Self-documenting code is better than comments every single time. Got a block of code of which it's not immediately clear what it does? Refactor it into a separate function with a descriptive name. Even if you're going to call that function only once, it makes the code easier to read and keeps the containing function short.

Nowadays I mainly use XML comments for my classes public interfaces. There are some comments here and there in the code itself, but mainly I just try to use clear identifiers to immediately convey what a function does or a class is for.

Oh, worst thing I've ever seen:

// Increment i
i++;

TommyCarlier
I want my scalps!

Bas: "increment" is a very technical term. Wouldn't "get the value of i, add 1 to it and store it back in i" be better?

evildictaitor
if( !succeed( try() ) ) { while(true) try(); }

leighsword wrote:

cheong wrote:As an inhouse developer, since client requirements change too frequently, the only "documentation for users" we can keep up-to-date is the ever growing "what's new" list between versions.

Upon 3+ years of continual development, I can tell you this list is long indeed. (Takes a few minutes to scroll to the bottom)

Haha, 'what's new' is good enough, a great software doesn't and never requires its document, see, do you check out the documentation of Media player when you are playing music?