Project Management question # 2 - Priorities

David Patrick

Again, for a team of 10 to 20 developers in size in what order would you prioritize the following "supplemental" activities : 1. reasonable code commenting/documentation 2. code reviews 3. unit testing Also, if you could only require your developers to do one of the above, which would it be ?

Rocket science is more fun when you actually have rockets - US Navy ad

Antony M Kancidrowski

1, 2 and 3 in that order. If you could only have any one then I choose 1

Ant. I'm hard, yet soft.
I'm coloured, yet clear.
I'm fruity and sweet.
I'm jelly, what am I? Muse on it further, I shall return! - David Walliams (Little Britain)

Xiangyang Liu

3, 2, 1 seems to be a more appropriate order. If developers don't even do unit testing, you won't have any confidence in their code review and documentation.

My .NET Business Application Framework My Home Page

NormDroid

1,2,3 1

.net is a box of never ending treasures, every day I get find another gem.

Duncan Edwards Jones

That seems like far too sensible a question - are you sure that you are a manager?[^]

'--8<------------------------ Ex Datis: Duncan Jones Merrion Computing Ltd

Hans Dietrich

reasonable code commenting/documentation The other two can be handled by other people.

Best wishes, Hans

[CodeProject Forum Guidelines] [How To Ask A Question] [My Articles]

Antony M Kancidrowski

You have to comment your unit tests...

Ant. I'm hard, yet soft.
I'm coloured, yet clear.
I'm fruity and sweet.
I'm jelly, what am I? Muse on it further, I shall return! - David Walliams (Little Britain)

krmed

I would suggest the most appropriate order for us is 1, 3, and 2 in that order. Resonable code commenting and documentation is a must for maintainability and for other developers to understand/modify the code as required. Unit test is a must before any release can be published. Code reviews insure adherance to standards and can catch obscure bugs (the major show-stoppers should be caught in the unit testing).

Karl - WK5M PP-ASEL-IA (N43CS) PGP Key: 0xDB02E193 PGP Key Fingerprint: 8F06 5A2E 2735 892B 821C 871A 0411 94EA DB02 E193

peterchen

a little bit more precise 1. reasonable code commenting/documentation 2. informal code reviews 3. unit testing Comments and documentatoon go first, because they are there to make the code accessible to other developers. (Imagine smeone put all your developers in one shuttle...) For 2 vs. 3.: I've switched - and switched back ;) I follow some statistics that suggest the best bug trap is someone else reading your code, and unit tests with high code and case coverage are an expensive investment. The tradeoff would be "less bugs" vs. "fast regression tests", which may depend on the project. Further, useful code reviews probably can be introduced at a later state easier than unit tests, so there's definitely wiggle room here.

We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
My first real C# project | Linkify!|FoldWithUs! | sighist

peterchen

If you lose all your developers, what will get the new guys on track fastest?

We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
My first real C# project | Linkify!|FoldWithUs! | sighist

Bob Flynn

I think working code will get them on track faster than well commented code. I find that comments are critical, but they also are easily outdated. Having tests that verify that code works and detects that it does not work when the new guy makes a change is most important. Some additional thoughts: I find that things that are not enforceable tend to be the most abouse/neglected. To make commenting and documentation the nmber 1 priority from a management perspective implies the need to track and verify that the comments are in place and accurate. Determining that comments are in place is easy enough with most (code coverage) tools available, but verifying that the comments are accurate requires code review as there are no tools that can do this for us. Unit tests provide a nice metric that is always up to date.

El Corazon

David Patrick wrote:

if you could only require your developers to do one of the above

If you were to sit on a one-legged stool, how comfortable would you feel? Would balancing precariously in the air make you feel unsure or powerful? I would not consider any of those "supplimental" though others do, including here. There were some mutterings when I got backing for pair-designing. It shortened code-reviews since design work, pre-code level, was already passing a mini-review by having been approved by two developers. It also reduced errors. This is the primary purpose behind unit tests and code reviews is to make a stable product BEFORE your software makes it to the customer. Code documentation and code commenting shouldn't even be optional, ever. I have had a long-time disagreement with one programmer, that has never been solved. Recently he returned to his work and asked my help in debugging his code, because he didn't even know what his code was doing. If that happens, it is pretty obvious that the comments are lacking. Code documentation and commenting is a maintenance issue. If you throw away all your code, rewrite everything and never reuse any code and none of your team ever talks to any other developer, and never tries to call any other developers code, ever, then perhaps it is not an issue. Otherwise, you are just asking for headaches, now, later, or both by not having good documentation -- especially including code comments.

_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)

Xiangyang Liu

peterchen wrote:

If you lose all your developers, what will get the new guys on track fastest?

Isn't that an extreme situation? I bet a developer has a better chance to out-run a tornado than a documentation cabinet. :-D

My .NET Business Application Framework My Home Page

El Corazon

Bob Flynn wrote:

but they also are easily outdated.

I have heard this argument ad nauseam. You could easily say, "unit tests can easily be forced to succeed and therefore should never be used." or "peer reviews are too easily swayed by cliques and therefore should never be done." or even "software can too easily create bugs, so no software should ever be written." Sure, if you don't do the work, it won't get done, but that should never be an exuse for not doing the work. When you put down a project for 6 months, the only clue to what ever the heck you were doing months ago, are your comments, or lack therein. If you have none, you have no idea what you were doing and easily create more bugs, misuse procedures, draw poor conclusions through too rapid review of your code, etc. So the result is at best the same as having unmaintained comments, and at worst, much, much worse. But if you actually do the work and maintain the comments, you get a plus by being able to know what you were doing 6 months ago. Everyone wins. No one should be asking for an essay on the history of the method you are doing and who has written it and what projects have succeed using the algorithm since 1960's. Access, purpose are the big requirements. How do you use it (input, output, calling/using methods) and intent/purpose. Given that a bug could easily be defined as an misunderstanding between the programmer's intended purpose (which hopefully is commented) and the physical interaction on the computer -- then a bug should be recognized as the difference between comment functionality and coded functionality. If you have no comments, then all bugs are a major search, every time because the debugging process must research and infer (never really knowing for sure) the original programmer's intent/purpose as well as evaluating functional run-time activity.

_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)

Andy Brummer

peterchen wrote:

If you lose all your developers,

I think only doing one out of the 3 is a great way to make that happen. ;)

Using the GridView is like trying to explain to someone else how to move a third person's hands in order to tie your shoelaces for you. -Chris Maunder

Andy Brummer

Is it an existing product, or is it new. If it is existing, code reviews are the easiest to add to an existing process. You also probably want to start with getting some high level documentation of the architecture and working in detail from the top down. Unit tests are notoriously tedious to write for existing code. I've found them much easier to write for new code and projects so you might want to work those in for new features and grow the library that way. Each of them tackle the same problem in different ways and are complementary. I'd rather work on a project that had some of all 3 then one that had just one done to the ninth degree.

Using the GridView is like trying to explain to someone else how to move a third person's hands in order to tie your shoelaces for you. -Chris Maunder

El Corazon

peterchen wrote:

If you lose all your developers, what will get the new guys on track fastest?

This is often listed as a doomsday scenerio, so not entirely accurate. Though you will find the argument said here with a very noticeable nod of the head. When they almost lost me in 2001, there was the sudden realization that they were loosing a massive knowledge of their software. There was one new developer on my work, and a couple of others that had no knowledge of the software I was doing... still it created a panic. You have you lead programmer on a major high-profile project dying in a hospital bed, the thing every manager waves off as "the doomsday scenerio" and too close to paranoia. And there they were, facing it in reality. I tend to not use it too often, but it is a constant reminder since my health has never been the same since. What happens if I die tomorrow? Though I think now that is less of a worry, there are still things only I know, but that is slowly changing. No one invented a brain-dumping mechanism. :)

_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)

Bob Flynn

El Corazon wrote:

I have heard this argument ad nauseam. You could easily say, "unit tests can easily be forced to succeed and therefore should never be used." or "peer reviews are too easily swayed by cliques and therefore should never be done." or even "software can too easily create bugs, so no software should ever be written."

Anything can be abused by someone deliberately trying to get around the system or artificially improve metrics. If there are team members or a management style the promotes/condones/or allows that to happen then none of the practices in the original post should be first on the list. Given that management and developers are serious about what they are doing and doing the best that they can, I think unit testing is the way to go. When I deliver code that is used and then found to have a bug in it, we try to address the bug, and then we try to write tests that would have detected that bug in the first place (along with other similar bugs) if possible. Now take the scenario where the choice is between commenting ONLY or testing ONLY. When I make a change to address a bug, if I write a test or tests that only pass when the proper criteria is met before passing the fix back to acceptance testing, there is verifiable proof that what I intended to code is what is actually coded. If I do not do the testing, but simply update my comments, how do I know if the code is doing what the comments say they are doing? Only by testing can that be determined. Testing also ensures that future changes do not yield unexpected results (if the tests are thorough). I am not saying that commenting is not critical. But I am saying that commenting does not verify that the code works the way it was designed to work or the way that the requirements state that it should work. Now, switching to your example, when you put down a project for 6 months. Well, when I pick up that project 6 months later, I want to see that the code base is properly intact and that it passes all of the tests that it was supposed to pass. Comments can not tell me anything about what is broken, they only describe what the code is supposed to do and how it is supposed to be used (I said only, but again I agree that comments are necessary). Comments do not say anything about how the code actually works - because there is a bug and the code is obviously not doing what the comments indicate that they do. So from a project management perspective, my first opinion is t

Xiangyang Liu

Your coworkers and manager will likely to survive fine even if you disappear permanently. This is not an attack on your skills or knowledge or importance. Even if you are the greatest developer alive, it will be very hard for the management to recognize or admit that. They can think of many other reasons why they have to hire 5 developers to continue your work: 1. The work you have been doing is just easy stuff, now they have to get started on more complicated tasks. 2. The technology you used is outdated, they need to rewrite everything from scratch. 3. There are so many hard to fix bugs in your code ... I think any manager will prefer 5 mediocre developers than a single person who thinks he is a super-star. :-D As they say, "the graveyard is full of indispensable people".

My .NET Business Application Framework My Home Page

peterchen

Well, yes. My line of thought was:"What is the worst that can happen?" But I don't prefer comments only for some worst case scenarios, rather it's the most basic thing for me. It's also the first thing I look for when I am thrown at an existing code base. With some expeirences in this regard, I am actually surprised that people would prefer unit tests over documentation. Documentaiton comes first also because the other two can be constructed from it. I rather have an /// \param X [void *] The target buffer, must be large enough to hold the results. May not be NULL. than a unit test that verifies the function throws an exception on a NULL parameter. Of course, I have high expectations towards documentation. (//increment i is not enough ;-)) I expect documentation to make the things clear that are not immediately visible locally from the code. What I see is that if you do have a comprehensive set of unit tests that do pass, you can expect a well-maintained code base, and there must be some contract documentation, otherwise there can't be good unit tests. So given a choice I might prefer the "project with good unit tests" over "the one with good documentation" - because the first implies that both is there. But that's reverse from the question.

We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
My first real C# project | Linkify!|FoldWithUs! | sighist