Goodbye to developer documentation?

Hi all,
I've been using Idea for around 2 years now, and I've just realised that I'm
writing less and less system documentation.

As a one-man team, the documentation has really just been for my own
benefit - UML diagrams explaining the more compex parts of my application's
architecture, sometimes backed up by a couple of paragraphs of text.

Now I've got used to Idea though, I can very quickly work through a
sub-system to find out what's happening. Well-structured code with good
comments is easy to navigate by ctrl-clicking on the method names.

This hasn't been a deliberate move by myself, I think it just is that the
requirement isn't there anymore - I never think "I'd better document this so
I can understand it again in 6 mths time".

Has anybody else found this?

cheers,
Ian


5 comments


ian mayo wrote:

I've been using Idea for around 2 years now, and I've just realised that I'm
writing less and less system documentation.


I've found myself writing more Javadoc. Perhaps it's because IDEA
makes it just a little bit less tedious with the tag/class/method
completions, smart joining of lines in Javadoc and autogeneration of the
@params, @throws, etc.

One shortcoming which I would really like fixed is autowrap within the
right margin for Javadoc. It's tedious and unnecessary work to do it
manually and could be easily done automatically. I've just created a
feature request for this if you feel the same way:
http://www.intellij.net/tracker/idea/viewSCR?publicId=9735.

Ciao,
Gordon

--
Gordon Tyler
Software Developer, R&D
Sitraka (now part of Quest Software)
"Performance is Mission Critical"

0


"Gordon Tyler" <gordon.tyler@sitraka.com> wrote in message
news:b1u43j$sbh$1@is.intellij.net...
>
>

I've found myself writing more Javadoc. Perhaps it's because IDEA
makes it just a little bit less tedious with the tag/class/method
completions, smart joining of lines in Javadoc and autogeneration of the
@params, @throws, etc.

>

Hi Gordon.

Yes, I am too writing more Javadoc, it's the separate documentation I'm on
about. For the largest of the applications I maintain I've a 100-or so Word
document containing dozens of various UML diagrams (mostly sequence &
class). I've been adding a section to it every now & then as I come across
something which might be difficult for me to get my head around in 6/12
months time. I realised I hadn't added to this in ages, and even the stuff
I thought I would need outside guidance to remember how it worked has become
transparent within Idea.

That's all

Ian


0

Yep, I agree. More powerful navigation and visualization features helps the
developer understand his application quicker. Powerful refactorings and
intentions along with good testing practices (enable by a seamless
integration) free the developer from the fear of changing something that
isn't broken. The good developer will then naturally invest time in making
the software itself more readable than "waste" time writing external
documentation (I mean waste because usually external docs and even javadocs
will eventually become obsolete unless it is part of the product: toolkit,
framework,libraries,...). BTW tests can be made to be good source of
documentation.

I truly believe that IDEA has made us more Agile than any other Ides.

Jacques
"ian mayo" <nospam.IanMayo@hotmail.com> wrote in message
news:b1uaj4$9ft$1@is.intellij.net...
>

"Gordon Tyler" <gordon.tyler@sitraka.com> wrote in message
news:b1u43j$sbh$1@is.intellij.net...
>
>

I've found myself writing more Javadoc. Perhaps it's because IDEA
makes it just a little bit less tedious with the tag/class/method
completions, smart joining of lines in Javadoc and autogeneration of the
@params, @throws, etc.

>

>

Hi Gordon.

>

Yes, I am too writing more Javadoc, it's the separate documentation I'm on
about. For the largest of the applications I maintain I've a 100-or so

Word

document containing dozens of various UML diagrams (mostly sequence &
class). I've been adding a section to it every now & then as I come

across

something which might be difficult for me to get my head around in 6/12
months time. I realised I hadn't added to this in ages, and even the

stuff

I thought I would need outside guidance to remember how it worked has

become

transparent within Idea.

>

That's all

>

Ian

>
>


0

As Martin Fowler says in 'Refactoring', if a method has to be documented
to be understood, it needs refactoring.

With IDEA (and I am a dummy user < 1 month usage), I see that each time
I hit a complex method, I refactor it and make the method names simpler
and to the point.

The side effect of this is almost a no-reason to javadoc condition.

anand

Jacques Morel wrote:

Yep, I agree. More powerful navigation and visualization features helps the
developer understand his application quicker. Powerful refactorings and
intentions along with good testing practices (enable by a seamless
integration) free the developer from the fear of changing something that
isn't broken. The good developer will then naturally invest time in making
the software itself more readable than "waste" time writing external
documentation (I mean waste because usually external docs and even javadocs
will eventually become obsolete unless it is part of the product: toolkit,
framework,libraries,...). BTW tests can be made to be good source of
documentation.

I truly believe that IDEA has made us more Agile than any other Ides.

Jacques
"ian mayo" <nospam.IanMayo@hotmail.com> wrote in message
news:b1uaj4$9ft$1@is.intellij.net...

>>"Gordon Tyler" <gordon.tyler@sitraka.com> wrote in message
>>news:b1u43j$sbh$1@is.intellij.net...
>>
>>>
>>>I've found myself writing more Javadoc. Perhaps it's because IDEA
>>>makes it just a little bit less tedious with the tag/class/method
>>>completions, smart joining of lines in Javadoc and autogeneration of the
>>>@params, @throws, etc.
>>>
>>
>>Hi Gordon.
>>
>>Yes, I am too writing more Javadoc, it's the separate documentation I'm on
>>about. For the largest of the applications I maintain I've a 100-or so


Word

>>document containing dozens of various UML diagrams (mostly sequence &
>>class). I've been adding a section to it every now & then as I come


across

>>something which might be difficult for me to get my head around in 6/12
>>months time. I realised I hadn't added to this in ages, and even the


stuff

>>I thought I would need outside guidance to remember how it worked has


become

>>transparent within Idea.
>>
>>That's all
>>
>>Ian
>>
>>



0

IDEA has definitely made documentation easier. I find my self writing and documenting much less after using IDEA. evrything is so easily understandable and accessible

__________
agile development methodology

0

Please sign in to leave a comment.