OT (slightly): Coordinating Multiple Developers

[Jesse Houwing]

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]

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

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]

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]

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]

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.

 

[Mark Wilden]

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