OT (slightly): Coordinating Multiple Developers

[Smithers]

Until now I have worked on small teams (1-3 developers) and we've been able
to stay out of each others way. Now I'm about to start work on a project
that will have 5 developers. I would appreciate some guidance on how we can
proceed to develop without having to worry about "who is working on what
files".

We're developing with SQL Server 2005, VS 2005 Pro (no way management is
going to spring for the $10,000 team edition for everybody), and we'll have
Visual SourceSafe.

Of course these tools (even the Team edition if we had it) wouldn't prevent
us from getting into trouble... thus my inquiry (for articles, links, tips,
suggestions, etc).

Thanks!

[sloan]

My advice is this:

Use good tiered development. This will help keep people out of each others
way.

(if someone is workign on the mypage.aspx, they won't interfere with someone
writing up a new business logic rule)

Have a "at the end of the day... you need to check in your code in a
buildable format"

aka, don't check something in that makes it so you can't compile.

Be very anal/strick about checking out the .sln and/or the .csproj (.vbproj)
files.

(Solution and Projects) because that will screw others.

This will keep things in order most of the time.

The biggest gotcha is that..

UserA creates a new file

MyNewClass.cs

They edit an existing class/file (MyExistingClass.cs), and write code in it
which uses MyNewClass (.cs)

They check out the project. They add the file.

They check in the project. They check in MyNewClass.cs.

They FORGET to check in MyNewClass.cs. Now others can't build.

A good ole boy policy of something like "The developer who does this has to
buy sodas for everyone else in the group" if they screw up can solve that
issue.

No, Im' not joking. A few rounds of sodas from the machine by the one
numbnutt who keeps forgetting, will burn some memory into him/her.



http://sholliday.spaces.msn.com/PersonalSpace.aspx 5/24/2006
6/5/2006

has a start up tiered development example:

"Smithers" <[e-mail]> wrote in message
news:OW**************@TK2MSFTNGP02.phx.gbl...

Until now I have worked on small teams (1-3 developers) and we've been able to stay out of each others way. Now I'm about to start work on a project
that will have 5 developers. I would appreciate some guidance on how we can proceed to develop without having to worry about "who is working on what
files".

We're developing with SQL Server 2005, VS 2005 Pro (no way management is
going to spring for the $10,000 team edition for everybody), and we'll have Visual SourceSafe.

Of course these tools (even the Team edition if we had it) wouldn't prevent us from getting into trouble... thus my inquiry (for articles, links, tips, suggestions, etc).

Thanks!

[Bob Powell [MVP]]

First of all, set up Sourcesafe so that developers can NEVER edit the same
file at once. A checkout should lock the file. This should really be the
case for all projects because if a file is big enough to be worked on by
more than one person it's probably hard to understand and in line for
refactoring anyway.

Make sure that you keep a close eye on the physical structure of your
program. The John Lakos C++ book is a superb guide, even for C# / VB
programmers because it describes in detail how physical organisation can
affect performance and build-times.

Use NDepends to get a handle on the metrics for your application and make
sure that all your developers understand why it's important.

Choose an XP / SCRUM / Agile development method rather than a spec and
MS-Project type of system. The former is flexible, the latter always gives
false expectations. Craig Larman once said to me "You often hear of software
delivered with all the features but months late and over budget. No one
*ever* complains if an application is deliverd on time but with only 90% of
the features"

Ensure that your development team has a good proportion of dedicated test
engineers. Three developers need one test engineer to keep them on the
rails.

Document EVERYTHING!!! from the word go. Use XML inline documentation and
keep it current.

Document your install procedures, your architecture, your dev practices and
do not allow hero-programmers to take stuff home in their heads and then get
themselves killed in a motor accident on the weekend. Those super-hero
programmers must transfer their skills to at least one other team member by
pair programming.

When a team is bigger than about 6, break it into two sub-teams. The team
lead will be the one who everyone listens to and who has the best ideas.
Don't bother trying to appoint one.

--
Bob Powell [MVP]
Visual C#, System.Drawing

Ramuseco Limited .NET consulting
http://www.ramuseco.com

Find great Windows Forms articles in Windows Forms Tips and Tricks
http://www.bobpowell.net/tipstricks.htm

Answer those GDI+ questions with the GDI+ FAQ
http://www.bobpowell.net/faqmain.htm

All new articles provide code in C# and VB.NET.
Subscribe to the RSS feeds provided and never miss a new article.

"Smithers" <[e-mail]> wrote in message
news:OW**************@TK2MSFTNGP02.phx.gbl...

Until now I have worked on small teams (1-3 developers) and we've been
able to stay out of each others way. Now I'm about to start work on a
project that will have 5 developers. I would appreciate some guidance on
how we can proceed to develop without having to worry about "who is
working on what files".

We're developing with SQL Server 2005, VS 2005 Pro (no way management is
going to spring for the $10,000 team edition for everybody), and we'll
have Visual SourceSafe.

Of course these tools (even the Team edition if we had it) wouldn't
prevent us from getting into trouble... thus my inquiry (for articles,
links, tips, suggestions, etc).

Thanks!

[Chris Dunaway]

Smithers wrote:

Of course these tools (even the Team edition if we had it) wouldn't prevent
us from getting into trouble... thus my inquiry (for articles, links, tips,
suggestions, etc).

This is an older article, but perhaps it will help:

http://msdn.microsoft.com/library/de...ml/tdlg_rm.asp

[Mark Wilden]

"sloan" <sl***@ipass.net> wrote in message
news:uo**************@TK2MSFTNGP05.phx.gbl...

Have a "at the end of the day... you need to check in your code in a
buildable format"
That would be altogether unworkable on many of the projects I've worked on.
aka, don't check something in that makes it so you can't compile.

That's a different matter, though, with which I agree.

Of course, an even better requirement is to not check in unless you've
refreshed your local copy and made all unit tests pass.

[Michael Brown]

> Until now I have worked on small teams (1-3 developers) and we've been

able to stay out of each others way. Now I'm about to start work on a
project that will have 5 developers. I would appreciate some guidance on
how we can proceed to develop without having to worry about "who is
working on what files".

We're developing with SQL Server 2005, VS 2005 Pro (no way management is
going to spring for the $10,000 team edition for everybody), and we'll
have Visual SourceSafe.

To be perfectly blunt, this really is the least of your worries (with all
due respect). You have SourceSafe so as long as everyone is checking out
their files there should be little conflict (assuming nobody needs to fight
over the same file all the time - parcel the files accordingly to avoid
this - it shouldn't be much trouble). The real problem you should focus on
is poorly written code (bad design, bad mechanics, lack of re-usability,
lack of error checking/recovery, etc). This is responsible for 99% of all
software problems and it's what everyone should be focusing most of their
time on:)

[Mark Wilden]

"Bob Powell [MVP]" <bob@_spamkiller_.bobpowell.net> wrote in message
news:ON**************@TK2MSFTNGP04.phx.gbl...

First of all, set up Sourcesafe so that developers can NEVER edit the same
file at once. A checkout should lock the file. This should really be the
case for all projects because if a file is big enough to be worked on by
more than one person it's probably hard to understand and in line for
refactoring anyway.
I used to feel this way, too. And it's the default in VSS, so most people
have never even tried using optimistic locking (where files aren't locked).
But once I actually tried multiple checkouts, life became soooo much easier.
No more dealing with the developer who leaves the office (or the company)
early. No more haggling over who gets to edit a file. Essentially, no more
concern with source control -- it becomes a useful tool, rather than a
prison.

What do you lose with multiple checkouts? Surprisingly little (especially if
you have a good set of unit tests). It's remarkably rare for two developers
to be working on the same part of the same file (if they are, that may
indicate problems that source control was never designed to solve). If two
developers are working on different parts of the same file at the same time,
modern merge tools have a laughably easy time sorting things out. Try it!
Document EVERYTHING!!! from the word go. Use XML inline documentation and
keep it current.
This is really anti-Agile, IMHO. The code is the documentation. If it
doesn't explain itself well enough, then make it simpler. If you can't do
that, then add comments, but only then.
Document your install procedures, your architecture, your dev practices
and do not allow hero-programmers to take stuff home in their heads and
then get themselves killed in a motor accident on the weekend. Those
super-hero programmers must transfer their skills to at least one other
team member by pair programming.

Again, I agree and disagree. Don't document install procedures -- automate
them. Make your documentation executable and it will never go out of date.
And if you pair-program, you don't need to document your dev practices.

I agree with most of your other points, however. :)

///ark

[Matt]

Mark Wilden wrote:

"Bob Powell [MVP]" <bob@_spamkiller_.bobpowell.net> wrote in message
news:ON**************@TK2MSFTNGP04.phx.gbl...

First of all, set up Sourcesafe so that developers can NEVER edit the same
file at once. A checkout should lock the file. This should really be the
case for all projects because if a file is big enough to be worked on by
more than one person it's probably hard to understand and in line for
refactoring anyway.
I used to feel this way, too. And it's the default in VSS, so most people
have never even tried using optimistic locking (where files aren't locked).
But once I actually tried multiple checkouts, life became soooo much easier.
No more dealing with the developer who leaves the office (or the company)
early. No more haggling over who gets to edit a file. Essentially, no more
concern with source control -- it becomes a useful tool, rather than a
prison.

What do you lose with multiple checkouts? Surprisingly little (especially if
you have a good set of unit tests). It's remarkably rare for two developers
to be working on the same part of the same file (if they are, that may
indicate problems that source control was never designed to solve). If two
developers are working on different parts of the same file at the same time,
modern merge tools have a laughably easy time sorting things out. Try it!

I happen to use Subversion, rather than SourceSafe, and prefer the
optimistic
locking approach. Just let multiple people work on things, merge them,
and fix
the resulting collisions. It doesn't happen all that often.

Document EVERYTHING!!! from the word go. Use XML inline documentation and
keep it current.
This is really anti-Agile, IMHO. The code is the documentation. If it
doesn't explain itself well enough, then make it simpler. If you can't do
that, then add comments, but only then.

Ick ick ick, EW. The code is NOT the documentation. The code just tells
you
what it DOES. The code does NOT tell what it was intended to do. I've
been a
maintenance programmer too often to believe the code. If the code were
always
right, we'd never have bugs.

Document your install procedures, your architecture, your dev practices
and do not allow hero-programmers to take stuff home in their heads and
then get themselves killed in a motor accident on the weekend. Those
super-hero programmers must transfer their skills to at least one other
team member by pair programming.
Again, I agree and disagree. Don't document install procedures -- automate
them. Make your documentation executable and it will never go out of date.
And if you pair-program, you don't need to document your dev practices.

Hm. I think you have to document all procedures to some point. I agree
that
automation is preferable, but bear in mind that these things will need
to be changed
at some point (in all likelihood). Having it documented makes it easier
to modify
things, especially if you didn't write it in the first place. There's
nothing bad about
documenting intent.

I agree with most of your other points, however. :)

Me too.

Matt

[Smithers]

Thanks Chris, the link is to a resource that presents *exactly* the sort of
guidance I was looking for.

-S


"Chris Dunaway" <du******@gmail.com> wrote in message
news:11*********************@c74g2000cwc.googlegro ups.com...

Smithers wrote:

Of course these tools (even the Team edition if we had it) wouldn't
prevent
us from getting into trouble... thus my inquiry (for articles, links,
tips,
suggestions, etc).

This is an older article, but perhaps it will help:

http://msdn.microsoft.com/library/de...ml/tdlg_rm.asp

[Smithers]

Thanks for jumping in, Michael:

RE:
<< To be perfectly blunt, this really is the least of your worries... >>

LOL!

<< (with all due respect) >>

ROTFLMAO!!!

<< The real problem you should focus on is poorly written code...>>

Well, as long as we're searching high and low for the *real* problem (which
I somehow missed), I'll have to say that I somehow need to figure out how to
articulate a good question to the NG without having to list all of the
assumptions my question makes... like "assuming a team of developers who
make it a huge priority to write tight code...."

-S

Oh, and : )
"Michael Brown" <no_spam@_nospam.com> wrote in message
news:%2****************@TK2MSFTNGP05.phx.gbl...

Until now I have worked on small teams (1-3 developers) and we've been
able to stay out of each others way. Now I'm about to start work on a
project that will have 5 developers. I would appreciate some guidance on
how we can proceed to develop without having to worry about "who is
working on what files".

We're developing with SQL Server 2005, VS 2005 Pro (no way management is
going to spring for the $10,000 team edition for everybody), and we'll
have Visual SourceSafe.

To be perfectly blunt, this really is the least of your worries (with all
due respect). You have SourceSafe so as long as everyone is checking out
their files there should be little conflict (assuming nobody needs to
fight over the same file all the time - parcel the files accordingly to
avoid this - it shouldn't be much trouble). The real problem you should
focus on is poorly written code (bad design, bad mechanics, lack of
re-usability, lack of error checking/recovery, etc). This is responsible
for 99% of all software problems and it's what everyone should be focusing
most of their time on:)

[Mark Wilden]

"Matt" <ma********@sprynet.com> wrote in message
news:11**********************@c74g2000cwc.googlegr oups.com...

I happen to use Subversion, rather than SourceSafe, and prefer the
optimistic
locking approach. Just let multiple people work on things, merge them, and
fix
the resulting collisions. It doesn't happen all that often.
I use Subversion, too, and I agree.
Ick ick ick, EW. The code is NOT the documentation. The code just tells
you what it DOES. The code does NOT tell what it was intended to do.
If the code doesn't tell you what it's intended to do, then it's wrong.
I've been a maintenance programmer too often to believe the code. If the
code were
always right, we'd never have bugs.
That's why unit tests are better documention than some Word file that gets
updated just about ... never. Instead of stopping coding to write
documentation, continue coding and write a test that a) shows what the code
is intended to do, and b) -proves- that this is the case.
Hm. I think you have to document all procedures to some point. I agree
that automation is preferable, but bear in mind that these things will
need
to be changed at some point (in all likelihood). Having it documented
makes it easier
to modify things, especially if you didn't write it in the first place.
There's
nothing bad about documenting intent.

The problem with documentation is a) it doesn't ship the current product (it
only makes shipping the next product easier), hence b) no one has time to do
it, hence c) it's always out of date, and d) no one uses it.

If your experience is different, my hat's off to you and your teams! :)

[Cowboy \(Gregory A. Beamer\)]

As long as you have exclusive checkouts, you should be fine. Just make sure
you have one person create the web projects and get them correctly into
source safe. Then, the others check out the source and right click web
project folders to make them virtual directories (web sharing under
properties).

The most difficult part is getting things into SourceSafe. If you use the
default method in Visual Studio it makes really crappy folders for web
projects, IMO. This is esp. true with websites.

The way I do it is create the project underneath the root where you are
having SourceSafe root working folder. You then create a folder for the new
project and check in the files. Even if this is an existing website, get it
checked in first, because working with multiple directories is a royal pain.
After you have it in, delete everything in the folder and get latest and
make sure you can still start up the web site. If so, get the other devs to
check out and create a virtual root for the web project. Make sure they can
connect. If everything is good, have one person open the project and put any
other web files in the project by add existing file(s). You can create
directories, etc. and then check the whole thing in. Now everyone should be
fine.

NOTE: For other types of projects, like class libs and smart clients, it is
not as hard.

If you want multiple people on the same file, you can aim for Vault, as
SourceSafe is not a good system for merging. Vault is not horribly expensive
and much faster at retrieve than SourceSafe.

As far as Team System goes, the MSDN subs with the Team SKUs (you do not
have to have Team Suite, any of the SKUs is able to connect (I would
recommend developer if you go this direction)). You also get Workgroup
edition of Team Foundation Server, which works with up to five people. If
you add more, you will have to upgrade to the full TFS, which is about $3k.
If you already have MSDN, you can do a free upgrade to the Team product of
your choice. I would consider one upgrade to Team Suite, if budget allows,
but it is not necessary.

--
Gregory A. Beamer

*************************************************
Think Outside the Box!
*************************************************
"Smithers" <[e-mail]> wrote in message
news:OW**************@TK2MSFTNGP02.phx.gbl...

Until now I have worked on small teams (1-3 developers) and we've been
able to stay out of each others way. Now I'm about to start work on a
project that will have 5 developers. I would appreciate some guidance on
how we can proceed to develop without having to worry about "who is
working on what files".

We're developing with SQL Server 2005, VS 2005 Pro (no way management is
going to spring for the $10,000 team edition for everybody), and we'll
have Visual SourceSafe.

Of course these tools (even the Team edition if we had it) wouldn't
prevent us from getting into trouble... thus my inquiry (for articles,
links, tips, suggestions, etc).

Thanks!

[Mark Wilden]

"Cowboy (Gregory A. Beamer)" <No************@comcast.netNoSpamM> wrote in
message news:eo**************@TK2MSFTNGP03.phx.gbl...

If you want multiple people on the same file, you can aim for Vault, as
SourceSafe is not a good system for merging. Vault is not horribly
expensive and much faster at retrieve than SourceSafe.

I've worked with VSS and optimistic locking with a small team like
Smithers's, and it's fine. However, I do recommend Subversion, which is
free.

[Matt]

Mark Wilden wrote:

"Matt" <ma********@sprynet.com> wrote in message
news:11**********************@c74g2000cwc.googlegr oups.com...

I happen to use Subversion, rather than SourceSafe, and prefer the
optimistic
locking approach. Just let multiple people work on things, merge them, and
fix
the resulting collisions. It doesn't happen all that often.
I use Subversion, too, and I agree.

Ick ick ick, EW. The code is NOT the documentation. The code just tells
you what it DOES. The code does NOT tell what it was intended to do.

If the code doesn't tell you what it's intended to do, then it's wrong.

The code is quite often wrong. The problem I find is that people THINK
the code
tells you what it is doing. Unfortunately, without some background in
what the
code was intended to do (the problem we are solving) it is difficult to
know if the
code is right or not.

I've been a maintenance programmer too often to believe the code. If the
code were
always right, we'd never have bugs.
That's why unit tests are better documention than some Word file that gets
updated just about ... never. Instead of stopping coding to write
documentation, continue coding and write a test that a) shows what the code
is intended to do, and b) -proves- that this is the case.

I've had this discussion with people before. You are right, in that
unit tests and
such are useful. For any large scale system, however, unit tests are
often more
optimistic than you would like to think. Simple test coverage doesn't
show up
problems that occur over periods of time in real-time systems, for
example. And
the chances of you covering all possible data irregularities is .. to
be kind.. unlikely.

You make a good case about the documentation not being updated. This is
a
serious problem and one that should be considered when writing the code
in the
first place. A change to the code that is not reflected in a change to
the documentation is a worthless change. That's why my groups usually
have documentation testing at both the user and programmer levels.

Hm. I think you have to document all procedures to some point. I agree
that automation is preferable, but bear in mind that these things will
need
to be changed at some point (in all likelihood). Having it documented
makes it easier
to modify things, especially if you didn't write it in the first place.
There's
nothing bad about documenting intent.
The problem with documentation is a) it doesn't ship the current product (it
only makes shipping the next product easier), hence b) no one has time to do
it, hence c) it's always out of date, and d) no one uses it.

Yeah, I know. But that's not the documentation's fault. That's the
fault of whoever
didn't update it, or his/her manager. The fact that documentation is
rarely done right
doesn't make it less valuable. That's like saying code is worthless
because every non-trivial application has bugs.

If your experience is different, my hat's off to you and your teams! :)

I've had good and bad experiences with docs. I'm not really disagreeing
with you,
there's never time allocated to do documentation right. Maybe we can
change that,
however.

Thanks for the discussion, its been valuable.

Matt

[Mark Wilden]

"Matt" <ma********@sprynet.com> wrote in message
news:11**********************@u72g2000cwu.googlegr oups.com...

The code is quite often wrong.
Of course, "quite often" is not an exact quantification, but I have not
worked anywhere where the code was what I'd call "often wrong," nor would I.
The problem I find is that people THINK
the code tells you what it is doing. Unfortunately, without some
background in
what the code was intended to do (the problem we are solving) it is
difficult to
know if the code is right or not.
Again, that's where tests come in.
I've had this discussion with people before. You are right, in that
unit tests and such are useful.
For me, they're essential. I do Test-Driven Development (TDD), where I write
no new code without a failing test. In other words, I don't fix a bug until
I have an automated test that exposes the bug. And I don't write a new
feature until I have a test that proves that feature is missing.
For any large scale system, however, unit tests are
often more optimistic than you would like to think. Simple test coverage
doesn't
show up problems that occur over periods of time in real-time systems, for
example. And the chances of you covering all possible data irregularities
is .. to
be kind.. unlikely.
You're talking about a different kind of testing than I am. TDD, it is often
said, isn't about testing. I think that's somewhat overboard, but it has a
kernel of truth. You're not pretending to be a QAer, whereby you verify that
the code is 100% bug-free. Rather, you're expressing in tests what the code
is supposed to do. It's a way of designing and documenting. It does have the
benefit of reducing bugs, but that's not its purpose, until you start
refactoring (improving the design without changing its functionality).
You make a good case about the documentation not being updated. This is
a serious problem and one that should be considered when writing the code
in the first place. A change to the code that is not reflected in a change
to
the documentation is a worthless change.
I almost agree, except that I replace "documentation" with "test." Code that
doesn't have tests is worthless, IMO.
Yeah, I know. But that's not the documentation's fault. That's the
fault of whoever didn't update it, or his/her manager. The fact that
documentation is
rarely done right doesn't make it less valuable. That's like saying code
is worthless
because every non-trivial application has bugs.
But coding is not "rarely done right," whereas documentation is. In a
perfect world, documentation might be the answer to improving the quality of
code. In this world, TDD (IMO) is the best way to achieve this.

If your experience is different, my hat's off to you and your teams! :)

I've had good and bad experiences with docs. I'm not really disagreeing
with you, there's never time allocated to do documentation right. Maybe we
can
change that, however.

The trouble is that documentation quality has been bemoaned since Day 1, and
nothing seems to be able to improve it. The reason (I feel) tests are better
is that you can automatically prove whether or not they document the code.
Thanks for the discussion, its been valuable.

Same here, Matt. You can probably tell I'm a bit of a fanatic about TDD. In
fact, I just got back from a Bay Area XP meeting, where we spent four hours
talking about this stuff. :)

[Cowboy \(Gregory A. Beamer\)]

With a small team, that is probably true. I would personally use anything
but SourceSafe.

Subversion is not a bad system, so I can certainly concur with the choice. I
am rather partial to Team System now, but it can get pricey for small
companies.

--
Gregory A. Beamer

*************************************************
Think Outside the Box!
*************************************************
"Mark Wilden" <Ma********@newsgroups.nospam> wrote in message
news:ug**************@TK2MSFTNGP03.phx.gbl...

"Cowboy (Gregory A. Beamer)" <No************@comcast.netNoSpamM> wrote in
message news:eo**************@TK2MSFTNGP03.phx.gbl...

If you want multiple people on the same file, you can aim for Vault, as
SourceSafe is not a good system for merging. Vault is not horribly
expensive and much faster at retrieve than SourceSafe.

I've worked with VSS and optimistic locking with a small team like
Smithers's, and it's fine. However, I do recommend Subversion, which is
free.

[Bob Powell [MVP]]

I can assure you that when you see four teams with over 30 developers think
that they can share a file and modify method signatures at-will you will
beleive absolutely in no multiple checkouts.

Anti-agile or no, when one is at the wrong end of a 1.5 million line project
that has no documentation whatsoever and a maintenance cost of over 80% of
budget one begins to believe strongly in the power of documentation and the
futility of adopting agile methodologies in legacy code.

Good development is all about communication and maintaining intellectual
property. This implies documentation and sharing of knowledge. Remember,
only primitive societies maintain an oral history, then they grow up and
learn to make documents.

--
Bob Powell [MVP]
Visual C#, System.Drawing

Ramuseco Limited .NET consulting
http://www.ramuseco.com

Find great Windows Forms articles in Windows Forms Tips and Tricks
http://www.bobpowell.net/tipstricks.htm

Answer those GDI+ questions with the GDI+ FAQ
http://www.bobpowell.net/faqmain.htm

All new articles provide code in C# and VB.NET.
Subscribe to the RSS feeds provided and never miss a new article.

"Mark Wilden" <Ma********@newsgroups.nospam> wrote in message
news:%2****************@TK2MSFTNGP05.phx.gbl...

"Bob Powell [MVP]" <bob@_spamkiller_.bobpowell.net> wrote in message
news:ON**************@TK2MSFTNGP04.phx.gbl...

First of all, set up Sourcesafe so that developers can NEVER edit the
same file at once. A checkout should lock the file. This should really be
the case for all projects because if a file is big enough to be worked on
by more than one person it's probably hard to understand and in line for
refactoring anyway.

I used to feel this way, too. And it's the default in VSS, so most people
have never even tried using optimistic locking (where files aren't
locked). But once I actually tried multiple checkouts, life became soooo
much easier. No more dealing with the developer who leaves the office (or
the company) early. No more haggling over who gets to edit a file.
Essentially, no more concern with source control -- it becomes a useful
tool, rather than a prison.

What do you lose with multiple checkouts? Surprisingly little (especially
if you have a good set of unit tests). It's remarkably rare for two
developers to be working on the same part of the same file (if they are,
that may indicate problems that source control was never designed to
solve). If two developers are working on different parts of the same file
at the same time, modern merge tools have a laughably easy time sorting
things out. Try it!

Document EVERYTHING!!! from the word go. Use XML inline documentation and
keep it current.

This is really anti-Agile, IMHO. The code is the documentation. If it
doesn't explain itself well enough, then make it simpler. If you can't do
that, then add comments, but only then.

Document your install procedures, your architecture, your dev practices
and do not allow hero-programmers to take stuff home in their heads and
then get themselves killed in a motor accident on the weekend. Those
super-hero programmers must transfer their skills to at least one other
team member by pair programming.

Again, I agree and disagree. Don't document install procedures -- automate
them. Make your documentation executable and it will never go out of date.
And if you pair-program, you don't need to document your dev practices.

I agree with most of your other points, however. :)

///ark

[Bob Powell [MVP]]

> If the code doesn't tell you what it's intended to do, then it's wrong.

That'll get you through loads of job interviews with people who actually
know their elbows from less apparent parts of their anatomies.

How many man-days would you loose on a team if you had to tell every new
developer "Go read the code and come back when you understand" ?

Why do you think MS provide MSDN?. It's not a benevolent method to keep
document writers in work you know.

--
Bob Powell [MVP]
Visual C#, System.Drawing

Ramuseco Limited .NET consulting
http://www.ramuseco.com

Find great Windows Forms articles in Windows Forms Tips and Tricks
http://www.bobpowell.net/tipstricks.htm

Answer those GDI+ questions with the GDI+ FAQ
http://www.bobpowell.net/faqmain.htm

All new articles provide code in C# and VB.NET.
Subscribe to the RSS feeds provided and never miss a new article.

"Mark Wilden" <Ma********@newsgroups.nospam> wrote in message
news:uz**************@TK2MSFTNGP05.phx.gbl...

"Matt" <ma********@sprynet.com> wrote in message
news:11**********************@c74g2000cwc.googlegr oups.com...

I happen to use Subversion, rather than SourceSafe, and prefer the
optimistic
locking approach. Just let multiple people work on things, merge them,
and fix
the resulting collisions. It doesn't happen all that often.

I use Subversion, too, and I agree.

Ick ick ick, EW. The code is NOT the documentation. The code just tells
you what it DOES. The code does NOT tell what it was intended to do.

If the code doesn't tell you what it's intended to do, then it's wrong.

I've been a maintenance programmer too often to believe the code. If the
code were
always right, we'd never have bugs.

That's why unit tests are better documention than some Word file that gets
updated just about ... never. Instead of stopping coding to write
documentation, continue coding and write a test that a) shows what the
code is intended to do, and b) -proves- that this is the case.

Hm. I think you have to document all procedures to some point. I agree
that automation is preferable, but bear in mind that these things will
need
to be changed at some point (in all likelihood). Having it documented
makes it easier
to modify things, especially if you didn't write it in the first place.
There's
nothing bad about documenting intent.

The problem with documentation is a) it doesn't ship the current product
(it only makes shipping the next product easier), hence b) no one has time
to do it, hence c) it's always out of date, and d) no one uses it.

If your experience is different, my hat's off to you and your teams! :)

[Mark Wilden]

"Bob Powell [MVP]" <bob@_spamkiller_.bobpowell.net> wrote in message
news:%2****************@TK2MSFTNGP02.phx.gbl...

If the code doesn't tell you what it's intended to do, then it's wrong.
That'll get you through loads of job interviews with people who actually
know their elbows from less apparent parts of their anatomies.

Actually, I've decided never again to interview with companies that aren't
agile, and who don't understand the views I've expressed in these posts.
How many man-days would you loose on a team if you had to tell every new
developer "Go read the code and come back when you understand" ?
They're going to have to read the code anyway. Far better for them to read
it than to think they'll actually understand the codebase after reading the
(typical) documentation.

(Mind you, I'm not saying there aren't very large shops where documentation
is kept up-to-date. I've never worked for one, and I don't think most
developers have, either, judging from the help-wanted ads.)
Why do you think MS provide MSDN?. It's not a benevolent method to keep
document writers in work you know.

MSDN is library documentation.

[Mark Wilden]

"Bob Powell [MVP]" <bob@_spamkiller_.bobpowell.net> wrote in message
news:Or**************@TK2MSFTNGP03.phx.gbl...

I can assure you that when you see four teams with over 30 developers think
that they can share a file and modify method signatures at-will you will
beleive absolutely in no multiple checkouts.
I don't credit "assurances" from people who have such an emotional
attachment to their viewpoints. Instead, I tend to learn from folks like
Mike Mason, the author of "Pragmatic Version Control."

Anway, I'm sorry you work with such lousy teams. If you worked with better
people, you might respect the agile viewpoint more.
Anti-agile or no, when one is at the wrong end of a 1.5 million line
project that has no documentation whatsoever and a maintenance cost of
over 80% of budget one begins to believe strongly in the power of
documentation and the futility of adopting agile methodologies in legacy
code.
See above.
Good development is all about communication and maintaining intellectual
property. This implies documentation and sharing of knowledge. Remember,
only primitive societies maintain an oral history, then they grow up and
learn to make documents.

I'm saying the code is the documentation. What does that have to do with
oral history?

[Jesse Houwing]

Mark Wilden wrote:

If your experience is different, my hat's off to you and your teams! :)

I've had good and bad experiences with docs. I'm not really disagreeing
with you, there's never time allocated to do documentation right. Maybe we
can
change that, however.

The trouble is that documentation quality has been bemoaned since Day 1, and
nothing seems to be able to improve it. The reason (I feel) tests are better
is that you can automatically prove whether or not they document the code.

Unless they're missing or bugged by themselves. I've seen it happen.

Also there are a number of fields that are hard to test automatically.
For me those are user interfaces and actual production specific
dependencies (the actual production payment gateway for example, real
life database content is often another).

You can test against a stub, or against a second server that doesn't
actually charge anyone, but there's always the question if those
services behave exactly the same as you've 'documented' using your tests.

Jesse

[Jesse Houwing]

Why do you think MS provide MSDN?. It's not a benevolent method to keep
document writers in work you know.

MSDN is library documentation.

At a certain point a lot of code in large companies transcends into the
status of "library code". A large number of companies will at some point
collect a large number of handy bits and pieces and put together their
own enterprise framework thingy. Those are often the worst libraries
when they don't come with solid documentation that is up to date.
Especially if you're into contracting like I am.

Other examples where documentation is a must, are services provided to
other departments or even to other customers. Especially if the team
maintaining said service is located at the other side of the planet and
never awake when you are.

Jesse

[Jesse Houwing]

>> Good development is all about communication and maintaining intellectual

property. This implies documentation and sharing of knowledge. Remember,
only primitive societies maintain an oral history, then they grow up and
learn to make documents.

I'm saying the code is the documentation. What does that have to do with
oral history?

In another post you said that you don't need documentation for
development practices for example as long as you pair program. This
implies oral history.

As long as there are members in the team that can transfer the knowledge
by training new team members al is well. Things might start to suck big
time when one of you big contractors goes bankrupt or if a number of
employees decide to leave the company all at the same time.

This won't work when you're the one who has to do the maintenance after
6 months of radio silence and internal deliberation at your client.
There are so many factors that require at least some level of written
documentation, apart from unit tests and automated build procedures.

I do agree that test driven development can save a lot of documentation
effort and that automated builds and deployment can also take away some
need for thick stacks of paper, but in the end there's always some
documentation to maintain.

Jesse Houwing

[Mark Wilden]

"Jesse Houwing" <je***********@nospam-sogeti.nl> wrote in message
news:uu**************@TK2MSFTNGP02.phx.gbl...

Mark Wilden wrote:

The trouble is that documentation quality has been bemoaned since Day 1,
and nothing seems to be able to improve it. The reason (I feel) tests are
better is that you can automatically prove whether or not they document
the code.
Unless they're missing or bugged by themselves. I've seen it happen.

Of course. The question is whether the tests (especially those produced by
TDD) are missing and/or buggy more or less frequently than documentation. In
my experience, there's really no contest.
Also there are a number of fields that are hard to test automatically. For
me those are user interfaces and actual production specific dependencies
(the actual production payment gateway for example, real life database
content is often another).
That's true. However, in those cases, even a non-automatic test is better
IMO than most documentation, because it can be proven.
You can test against a stub, or against a second server that doesn't
actually charge anyone, but there's always the question if those services
behave exactly the same as you've 'documented' using your tests.

Well, that really addresses whether the tests prove the code is bugless,
which isn't what I'm really talking about. Even tests that use a lot of mock
objects should at least show what the code is supposed to be doing.

[Mark Wilden]

"Jesse Houwing" <je***********@nospam-sogeti.nl> wrote in message
news:eV**************@TK2MSFTNGP02.phx.gbl...

Why do you think MS provide MSDN?. It's not a benevolent method to keep
document writers in work you know.
MSDN is library documentation.

At a certain point a lot of code in large companies transcends into the
status of "library code".

Code is either library code, or it isn't. It doesn't matter what the size of
the company is. The code is either intended for reuse by other developers or
it isn't. If it is, it should be documented by well-chosen class and method
names, by tests, and by its own source code.
A large number of companies will at some point collect a large number of
handy bits and pieces and put together their own enterprise framework
thingy.
I don't think "handy bits and pieces" is the same thing as an enterprise
framework at all.

I will grant you that the greater the number of users of code, the more
useful external documentation is. I would first say, however, that it's even
more important that the code be expressively written, and intentionally
tested. I'd rather have that than external documentation.
Other examples where documentation is a must, are services provided to
other departments or even to other customers. Especially if the team
maintaining said service is located at the other side of the planet and
never awake when you are.

If the company has the money to write and maintain accurate external
documentation, that's fine. That hasn't been my experience, though.

[Mark Wilden]

"Jesse Houwing" <je***********@nospam-sogeti.nl> wrote in message
news:uA**************@TK2MSFTNGP03.phx.gbl...

I'm saying the code is the documentation. What does that have to do with
oral history?
In another post you said that you don't need documentation for development
practices for example as long as you pair program. This implies oral
history.

Right. I thought he was talking about code documentation, since that seemed
to be what the rest of his post was about.

If given a choice, I think we -all- would love to have completely accurate
and readable documentation of everything. I just think there are more
important things to spend precious resources on.
As long as there are members in the team that can transfer the knowledge
by training new team members al is well. Things might start to suck big
time when one of you big contractors goes bankrupt or if a number of
employees decide to leave the company all at the same time.
So we're talking about a company that successfully maintains its
documentation, but can't hang onto its most important assets? I don't think
such companies are very common.
This won't work when you're the one who has to do the maintenance after 6
months of radio silence and internal deliberation at your client. There
are so many factors that require at least some level of written
documentation, apart from unit tests and automated build procedures.
The trouble is that documentation is not trustable. The source code is.
I do agree that test driven development can save a lot of documentation
effort and that automated builds and deployment can also take away some
need for thick stacks of paper, but in the end there's always some
documentation to maintain.

The agile folks (of whom I'm a mere hanger-on) disagree. Far better to
refactor the code so it's readable, or write a more expressive test, than it
is to write documentation that is obsolete within the week. Again, if all
your documentation is accurate and up-to-date, this doesn't apply. I've just
never seen that happen.

[Ian Semmel]

Having spent a large proportion of my many years programming on maintenance
projects, I believe that the best way to ensure that systems are maintainable is
the adoption and rigorous adherence to programming standards, both in the way
code is written and program structure. I don't really care what the standards
are so long as everyone adheres to them. All programs within an organisation
should 'look' the same.

Programms tend to be fairly independent and each of us have our own ideas on
what a program should look like. What is needed is a despotic approach,
administered by a dictator type, who will ensure that the standards are followed.

Bob Powell [MVP] wrote:

I can assure you that when you see four teams with over 30 developers think
that they can share a file and modify method signatures at-will you will
beleive absolutely in no multiple checkouts.

Anti-agile or no, when one is at the wrong end of a 1.5 million line project
that has no documentation whatsoever and a maintenance cost of over 80% of
budget one begins to believe strongly in the power of documentation and the
futility of adopting agile methodologies in legacy code.

Good development is all about communication and maintaining intellectual
property. This implies documentation and sharing of knowledge. Remember,
only primitive societies maintain an oral history, then they grow up and
learn to make documents.

[Mark Wilden]

"Ian Semmel" <is***********@NOKUNKrocketcomp.com.au> wrote in message
news:%2****************@TK2MSFTNGP03.phx.gbl...

Having spent a large proportion of my many years programming on
maintenance projects, I believe that the best way to ensure that systems
are maintainable is the adoption and rigorous adherence to programming
standards, both in the way code is written and program structure. I don't
really care what the standards are so long as everyone adheres to them.
All programs within an organisation should 'look' the same.

The Agile viewpoint would, in general, agree with this, I believe.
Collective code ownership and pair-programming are both benefited by coding
standards. These standards can be documented, or simply inferred by reading
existing code.

///ark