[H-GEN] Code development and documentation methods

[ben.carlyle at invensys.com]

[ Humbug *General* list - semi-serious discussions about Humbug and     ]
[ Unix-related topics. Posts from non-subscribed addresses will vanish. ]

David Jericho <david.jericho at bytecomm.com.au>
Sent by: Majordomo <majordom at caliburn.humbug.org.au>
14/11/02 14:45
Please respond to general

 
        To:     general at humbug.org.au
        cc: 
        Subject:        [H-GEN] Code development and documentation methods

> Basically, as things are at the moment, the process for fixing a bug
> is

> * Identify bug and cause
> * Specify the fix to happen, in plain english w/hardcopy
> * Fix the code
> * Test the code 
> * Commit code
> * Record test results, and diff of changes with log of
>   changes w/hard copy

> What methods of documentation and appeasing those who command thou do
> other humbug members use? 

G'day,

I'm working in a team of roughly 4-8 people[1] on a project primarily for 
the MTR train network in Hong Kong. We use a commercial task-based 
source-code repository call "Continuous". While this alone was enough in 
our early stages of development the later stages which have involved a lot 
of graphs which are intended to improve customer confidence and visibility 
of our system during testing stages have used Bugzilla[3].

In terms of the process it's self we've tried to emulate some of the 
components of the "Extreme Programming" practice with reasonable success. 
We haven't gone all out in applying it, but what we have applied has been 
useful on many levels:

- Automated test cases.
If a test case is worth doing it's worth automating, at least at the lower 
levels. While system-level testing can be quite a bit of effort to 
automate bugs found in code that could be executed by an automated test 
with reasonable effort are best automated. Automated tests have a way of 
accumulating and making it easier to be sure of the quality of your 
software over time rather than harder. They should be run often, in fact 
we run them as part of the normal build cycle of every developer. We treat 
the bug-fixing cycle as something like this:
1. Determine a bug exists and form a hypothesis
2. Prove the hypothesis either manually or preferrably by constructing an 
automatic test case
3. Fix the code
4. Prove the new test case that was previously broken is now working
5. Close out and verify the bug at the system level

- Pair programming
Pair programming is a the concept of having two people at every keyboard. 
It's all code review, all the time.
We don't do this much, but in the cases were we have[4] we've often found 
that designs have come out much cleaner, bugs have been averted, and less 
time has been spent coming to the conclusion. A second pair of eyes and a 
second way of looking at not only this problem but all the inter-related 
code is an extremely useful thing even for very experienced programmers. 
It also is a way of forming the team and improving relationships as each 
member learns to trust and respect the technical areas that the other can 
deal with effectively. We have a slightly looser form of pair programming 
that we actually do use constantly and that is to communicate design ideas 
as they come up and discuss them very readily. Every bug is at least 
mentioned to another team member and this often leads to better code and 
better practices, especially for the less experienced team members.

- Noone owns the code
While major pieces of code are usually developed by a single person 
other's eventually start interacting with that code. When the interaction 
occurs other developers than just the original developer are actively 
encouraged to not only suggest modifications to interfaces and underlying 
code but to impliment them. This automatically leads to interactions which 
can be both positive and negative but again usually lead to a solid team 
that is capable of dealing with the code as a product and not as their 
property. It improves design as more than one perspective on code always 
does, and again is a useful training aid.

wrt the hard copy... we're not big on that. As our product enters the 
stage where it will not only be used for MTR but for other customers 
around the world we'll most likely focus more on that.. more on 
documentation of a formal nature. At this point, though, very little 
documention has actually been written. Obviously this could have some 
massive downsides where teams fall apart and noone can make use of the 
project collateral, or when it comes to share the product on a technical 
level with other development groups. My personal feeling is that it should 
be written down for posterity, however if you really want a technical 
dialogue you should come and talk to me and start playing with the code. 
Opinions will no doubt differ wildly on that point ;) On the other hand I 
suspect that heavy use of hard-copy-style documentation on our project 
would have left it dead in the water. The team was initially too 
inexperienced to build the product. The problem was too hard. While we had 
vauge ideas of how to produce the final result it's only through two years 
or writing the software and rewriting it when it was wrong that we've 
gotten to where we are. If we'd been producing detailed software design 
docuements all the way along that noone would have reviewed properly 
anyway we would have taken twice as long to get here and probably run out 
of steam half-way through. Instead of designing a massive system from the 
ground up and building it, we've build a massive system from the ground up 
adjusting and refining our rough designs as they needed doing. Many design 
ideas were left by the way-side. I suppose that leads us into the last 
"XP" principle that I think is worth mentioning in this email: The 
vertical slice.

When building a product you could design all the pieces, or the whole 
architecture of the software and then go and build it all in one hit. Once 
you've finished building the pieces you could integrate them, and then 
test them. The vertical slice is an alternative approach which emphasises 
delivering real products, if incomplete, all the way through your 
development cycle. You want to build a system for managing a train power 
system and environmental control system as our teams has. Instead of 
designing it from the ground up you start by developing a system for 
getting messages around, particularly subscriptions since that's what most 
of the final system will want to do. Once that works and you can take the 
experience of that with you, you make a system for storing synchronising 
data and then you start adding functions such as alarms, events, whatever. 
It's a process of constant integration of the software because integration 
will always be the highest risk activity in software development. It's a 
process of devering the things that will be most useful to the customer 
today if the project as a whole has to be scaled back for any reason. It's 
a process of seeing whole systems and the problems that occur on the 
macro-scale will require new ways of thinking about the lower-levels.

Anyway.

That's how we do things in my little neck of the woods :)

Benjamin.

[1] 4 basically full-time, other are occasional helper
[2] There really isn't that much good out there, and our customers 
insisted we have something along the lines of this product at the 
beginning of the project several years ago. The effort involved with 
changing to anything else is less than the effort involved with remaining 
as we are.
[3] I highly recommend this incident tracking system for small groups that 
just want a product that's easy to us.
[4] We would usually do this where a bug has shown some kind of design 
deficiency that is non-trivial to solve.


--
* This is list (humbug) general handled by majordomo at lists.humbug.org.au .
* Postings to this list are only accepted from subscribed addresses of
* lists 'general' or 'general-post'.  See http://www.humbug.org.au/