Where to document updates?

[Brett]

Where is a good place to document version updates to a simple program? This
isn't anything a user will see. Only developers.

I was thinking of including an empty class file just for documenting
revisions. They will only be comments.

Also, I'd like to put these comments in XML format. How can that be done
and where should it be stored? The program is just an EXE with no other
files. I'd like to keep it that way.

Thanks,
Brett

 

[Herfried K. Wagner [MVP]]

Where is a good place to document version updates to a simple program?
This isn't anything a user will see. Only developers.

I was thinking of including an empty class file just for documenting
revisions. They will only be comments.

No need for a class file. A class file is /source code/. What you want to
do is code/project /documentation/ for the developer.

Also, I'd like to put these comments in XML format. How can that be done
and where should it be stored? The program is just an EXE with no other
files. I'd like to keep it that way.

You can add an XML file to your project and set its 'Build Action' to
'None'.

 

[Andy O'Neill]

Where is a good place to document version updates to a simple program?
This isn't anything a user will see. Only developers.

I was thinking of including an empty class file just for documenting
revisions. They will only be comments.

Also, I'd like to put these comments in XML format. How can that be done
and where should it be stored? The program is just an EXE with no other
files. I'd like to keep it that way.

Thanks,
Brett

You will also need a big stick to beat the developers and make them fill out
such a file.

Personally, I would never trust such a piece of documentation unless it was
me wrote it.
I have worked on so many systems where the documentation and comments are
out of step with the actual code.

What I've seen work is where each change request is documented by someone
and the developers can only release code where they have a change request.
With these systems there was actually someone responsible for maintaining
change requests and the manager handed out work in terms of these.
Sourcesafe code had change request numbers commented into each version.
If you wanted to, you could use sourcesafe to track down specific code
changes between the versions and thus change requests.

I've also used the buddy/walkthrough technique where changes are discussed
with at least one other and there's a walkthrough of changes before putting
things live. This way at least two people understand what changes have been
made.

HTH

 

[Brett]

No need for a class file. A class file is /source code/. What you want
to do is code/project /documentation/ for the developer.


You can add an XML file to your project and set its 'Build Action' to
'None'.

On a Windows Form, the code that automatically creates form objects will
usually collapse so you don't see it. Clicking the plus sign on the left
side expands this code. Is there a way to do this with comments? I'd like
to add detailed code comments but don't want them mucking up the code view
when they aren't needed.

Thanks,
Brett

 

[Herfried K. Wagner [MVP]]

On a Windows Form, the code that automatically creates form objects will
usually collapse so you don't see it. Clicking the plus sign on the left
side expands this code. Is there a way to do this with comments? I'd
like to add detailed code comments but don't want them mucking up the code
view when they aren't needed.

Currently you can open/close comments which are placed in front of a class,
method, ... However, their state is not saved, so when you close the
project, the expanded/collapsed state gets lost. IIRC this will be "fixed"
in VB 2005.