14 Replies - 2132 Views - Last Post: 27 April 2012 - 04:29 PM

#1 NecroWinter  Icon User is offline

  • D.I.C Regular

Reputation: 35
  • View blog
  • Posts: 318
  • Joined: 21-October 11

Software Engineering (documentation)

Posted 16 April 2012 - 07:05 AM

How much of your time is spent with software engineering practices? Such as Object Oriented Analysis, documenting workflows etc.

I ask this, because the internships I had did not do anything like this, and now that im in a class with this stuff, i find myself more bored and uninterested than ive been in anything in years. Is being a programmer really dealing with mostly dull and formal documentation?
Is This A Good Question/Topic? 0
  • +

Replies To: Software Engineering (documentation)

#2 jon.kiparsky  Icon User is offline

  • Pancakes!
  • member icon


Reputation: 7572
  • View blog
  • Posts: 12,717
  • Joined: 19-March 11

Re: Software Engineering (documentation)

Posted 16 April 2012 - 07:33 AM

Depends on the workplace and the practices and the product. I'm in financial services, we document a lot, because we have to (SEC rules, audits, and such like). And the areas where it's not required, or where the audits aren't so stringent, we don't, and frankly those areas are the ones where we have the most problems.

Some questions to ask yourself:
  • how long will this product be in service?
  • how large is this product?
  • how many people will work on this product in its lifetime?
  • if this product is a service, what are the consequences of an extended outage?


If you're developing mobile apps, maybe there's less design and less documentation, analysis, and design, because, really, who cares? If you're deploying a web product that touches people's investments, there's a lot more of all three because, really, your customers will come to your office and lynch you if it fails for a few hours.

One interesting consequence of the first three rules is this: in most cases, it makes sense to do a lot more DAD work than you apparently want to do. Think about it this way: either your product will be a success, or it will be a failure. If it's a failure, it doesn't matter what you do - it'll sink like a stone and you'll never have to touch it again. So don't waste time building it to last.
On the other hand, if it's a success, it'll certainly be maintained, upgraded, extended, developed, and manhandled and mauled for a long time to come. In that case, that upfront work, and continued attention to documentation, will make that future work easier and more likely to succeed.

Another interesting thing to consider is one of Brooks' laws:

Quote

Build one to throw away. You'll throw one away in any case.


Doing the upfront design work is a useful investment in a product of any size because it amounts to building a prototype. It's everything a prototype should be: it's cheap (materials are free!) and quick (ideas are easy to work with) and ephemeral (you're not tempted to build the final product on a prototype skeleton). This allows you to get a lot of mistakes made and out of the way ahead of time, which speeds development down the line.
Was This Post Helpful? 0
  • +
  • -

#3 DarenR  Icon User is online

  • D.I.C Lover

Reputation: 433
  • View blog
  • Posts: 3,000
  • Joined: 12-January 10

Re: Software Engineering (documentation)

Posted 16 April 2012 - 07:57 AM

Before I came to my job there was 0 documentation. Now every bit of code I touch has some sort of documentation on just about every line.

I don't know about you but if I don't have to spend hours debugging code to find where the information is pulling from I actually get things done.
Was This Post Helpful? 0
  • +
  • -

#4 Sergio Tapia  Icon User is offline

  • D.I.C Lover
  • member icon

Reputation: 1252
  • View blog
  • Posts: 4,168
  • Joined: 27-January 10

Re: Software Engineering (documentation)

Posted 16 April 2012 - 09:25 AM

Since I'm self employed, I hardly document anything. I rely on Unit Testing to tell where something is going amiss, and use user stories to guide what the application should be doing. I haven't used UML since my 2nd year old university, and it was so boring and useless to me when a napkin would have been quicker and more useful.

Depending on where you work and the culture there you might be required to write long, boring and obvious documentation or quick lean documentation.

But at the very least you should document, even a little teeny tiny bit. Something is better than nothing.
Was This Post Helpful? 0
  • +
  • -

#5 jon.kiparsky  Icon User is offline

  • Pancakes!
  • member icon


Reputation: 7572
  • View blog
  • Posts: 12,717
  • Joined: 19-March 11

Re: Software Engineering (documentation)

Posted 16 April 2012 - 09:41 AM

Sergio - I've always considered unit tests to be a species of documentation more than anything else. And of course user stories document purpose, which is pretty important to get down. So perhaps you're doing more documentation than you think.
Was This Post Helpful? 0
  • +
  • -

#6 NecroWinter  Icon User is offline

  • D.I.C Regular

Reputation: 35
  • View blog
  • Posts: 318
  • Joined: 21-October 11

Re: Software Engineering (documentation)

Posted 16 April 2012 - 11:39 AM

View Postjon.kiparsky, on 16 April 2012 - 09:41 AM, said:

Sergio - I've always considered unit tests to be a species of documentation more than anything else. And of course user stories document purpose, which is pretty important to get down. So perhaps you're doing more documentation than you think.


Yeah, but im talking more formal documentation

how many people here have done object oriented analysis etc?
Was This Post Helpful? 0
  • +
  • -

#7 Ryano121  Icon User is offline

  • D.I.C Lover
  • member icon

Reputation: 1362
  • View blog
  • Posts: 3,002
  • Joined: 30-January 11

Re: Software Engineering (documentation)

Posted 16 April 2012 - 11:45 AM

Had to do loads of those damn things in my degree. Never used them since.
Was This Post Helpful? 0
  • +
  • -

#8 Sergio Tapia  Icon User is offline

  • D.I.C Lover
  • member icon

Reputation: 1252
  • View blog
  • Posts: 4,168
  • Joined: 27-January 10

Re: Software Engineering (documentation)

Posted 16 April 2012 - 11:48 AM

View PostNecroWinter, on 16 April 2012 - 02:39 PM, said:

View Postjon.kiparsky, on 16 April 2012 - 09:41 AM, said:

Sergio - I've always considered unit tests to be a species of documentation more than anything else. And of course user stories document purpose, which is pretty important to get down. So perhaps you're doing more documentation than you think.


Yeah, but im talking more formal documentation

how many people here have done object oriented analysis etc?


Only did it during college, never used it once during my professional career.
Was This Post Helpful? 0
  • +
  • -

#9 NecroWinter  Icon User is offline

  • D.I.C Regular

Reputation: 35
  • View blog
  • Posts: 318
  • Joined: 21-October 11

Re: Software Engineering (documentation)

Posted 16 April 2012 - 12:10 PM

im so happy to hear that, this stuff is dreadfully dull. I can work on a program where the purpose may not be interesting, and find a lot of joy in it, but this formal documentation stuff really makes me drag along lol
Was This Post Helpful? 0
  • +
  • -

#10 jon.kiparsky  Icon User is offline

  • Pancakes!
  • member icon


Reputation: 7572
  • View blog
  • Posts: 12,717
  • Joined: 19-March 11

Re: Software Engineering (documentation)

Posted 16 April 2012 - 12:34 PM

Quote

how many people here have done object oriented analysis etc?


Means what exactly? Sounds to me like "design it before you start thrashing at it" which seems like good advice to me, and standard practice, but maybe you mean something else.

Quote

im so happy to hear that, this stuff is dreadfully dull. I can work on a program where the purpose may not be interesting, and find a lot of joy in it, but this formal documentation stuff really makes me drag along lol


Don't go into financial services,then. Or anything else where there's anything serious riding on the code, really. Or anything that involves investors.
Was This Post Helpful? 0
  • +
  • -

#11 NecroWinter  Icon User is offline

  • D.I.C Regular

Reputation: 35
  • View blog
  • Posts: 318
  • Joined: 21-October 11

Re: Software Engineering (documentation)

Posted 16 April 2012 - 12:36 PM

View Postjon.kiparsky, on 16 April 2012 - 12:34 PM, said:

Quote

how many people here have done object oriented analysis etc?


Means what exactly? Sounds to me like "design it before you start thrashing at it" which seems like good advice to me, and standard practice, but maybe you mean something else.

Quote

im so happy to hear that, this stuff is dreadfully dull. I can work on a program where the purpose may not be interesting, and find a lot of joy in it, but this formal documentation stuff really makes me drag along lol


Don't go into financial services,then. Or anything else where there's anything serious riding on the code, really. Or anything that involves investors.



documention is fine. As long as it makes sense and doesnt detract from the actual production of the software.
Object Oriented Analysis is a formal documentation type in which you draw class diagrams, have stereotypes, draw sequence and commucation diagrams etc

you also treat a good chunk of the code as a class etc. Its meant to be similar in mindset to OOP

it just seems like the formal documentation types are excessive and detract from actual productive work. You have to memorize a bunch of things that ought to just be intuitive, and probably would be if someone simply wrote down in a logical way what they observe. It also seems like a lot of the concepts should probably be business specific. Meaning that a business should probably design their own protocols.

the fact that you dont seem to know what im talking about (not insulting you btw) kind of answers my question. Sure enough I have no problems with documentation its self

This post has been edited by NecroWinter: 16 April 2012 - 12:46 PM

Was This Post Helpful? 0
  • +
  • -

#12 jon.kiparsky  Icon User is offline

  • Pancakes!
  • member icon


Reputation: 7572
  • View blog
  • Posts: 12,717
  • Joined: 19-March 11

Re: Software Engineering (documentation)

Posted 16 April 2012 - 12:57 PM

Intuition has a nasty habit of failing. Formal procedures exist to backstop your intuition - to take away the option to forget to do something that will later turn out to be important.

Think of a checklist for a parachute jump. Do you really want to trust to intuition there?
Developing software doesn't feel like a parachute jump, but it's got one similarity: you only get one chance to do it right the first time. And in practical terms, you really want to get it right the first time. It takes a lot less time, and it's a lot less painful.
Was This Post Helpful? 0
  • +
  • -

#13 Craig328  Icon User is offline

  • I make this look good
  • member icon

Reputation: 1912
  • View blog
  • Posts: 3,442
  • Joined: 13-January 08

Re: Software Engineering (documentation)

Posted 16 April 2012 - 01:57 PM

My documentation consists really of just two parts:

1./ Comment/note my code where obvious and necessary (because I work with folks who absolutely don't notate anything in their code)
2./ Design the user interfaces with a level of user IQ in mind reminiscent of an autistic gibbon with a seeping head wound. Basically, if the simian with brain damage can figure out it, yer good.

Most of my work these days and for the past several years is on the administrative interfaces to a lot of things (although I do get to do a fair chunk of user facing stuff) so I get to assume a tiny amount of leeway insofar as user IQ goes. The more time you take mating clear, concise directions to intuitive interfaces = less time you need to take to document same. That's not to say the moment you believe the module you just worked on is documented enough that the universe doesn't automagically invent an even more untalented idiot to torture your code (because it totally does). It just means you get to curse a much smaller circle of folks when yer boss asks you to type up documentation for it.
Was This Post Helpful? 0
  • +
  • -

#14 jon.kiparsky  Icon User is offline

  • Pancakes!
  • member icon


Reputation: 7572
  • View blog
  • Posts: 12,717
  • Joined: 19-March 11

Re: Software Engineering (documentation)

Posted 16 April 2012 - 04:11 PM

Quote

The more time you take mating clear, concise directions to intuitive interfaces = less time you need to take to document same.


Amen to that. A large part of my time writing user-facing documentation is actually spent saying things like "I'd have a lot less explaining to do if the user didn't have to leave this screen and come over to this screen in order to get this thing done, and then click back over". By the time we're done, the documentation fits on a 3X5 index card.

But I don't think the question was about user-facing documentation - I think it was about internal docs. Programmers generally don't write the user-facing stuff, in my experience, but they're almost always heavily involved in the internal stuff, either on their own or with someone like me to hold their hand and get them through it.
Was This Post Helpful? 0
  • +
  • -

#15 wordswords  Icon User is offline

  • D.I.C Regular
  • member icon

Reputation: 76
  • View blog
  • Posts: 272
  • Joined: 17-December 11

Re: Software Engineering (documentation)

Posted 27 April 2012 - 04:29 PM

If you find yourself rewriting code frequently, for example in a spiral agile development model, where you are constantly rewriting and releasing.. I think unit tests make for far more sensible documentation than 'commenting each line'.

Commenting is great if you keep the comments updated every time you change the code. But this might result in twice the amount of effort, and often comments don't get updated when the team is racing towards a hard deadline. When comments become outdated, they are at best a nusiance, at worst completely misleading. And if you get yourself into a situation where some comments are outdated and others aren't.. then you don't know which comments to trust, and it all goes south.

Personally, unless you have a business mandate that says 'You Must Comment', I think you should strive for self-documenting code. This means adpoting a common coding standard in a team, adopting a common variable naming convention, and sticking to it. If you have a lot of experience in the language you are using, then this should be enough. I routinely have to trawl through code in multiple languages that doesn't have any comments, and doesn't use common standards, and I survive. It gets easier with practice.

You would still write design and architecture documentation, as well as transaction diagrams, user documentation, runbooks and other necessary 'documents'.. but commenting each line can actually be a lot more bother than it is worth.

This post has been edited by wordswords: 27 April 2012 - 04:32 PM

Was This Post Helpful? 0
  • +
  • -

Page 1 of 1