What's your habit to document this? - 未名空间MITBBS历史存档

国际科技财经博客移民网络热点娱乐民生时事公众号

Redian新闻

>未名空间

>Java - 爪哇娇娃

What's your habit to document this?

What's your habit to document this?# Java - 爪哇娇娃

g*y2005-09-02 07:09

1 楼

In a program, there are three blocks, A, B, C.
A must run before C, because C will change some data A depends on.
In logic flow, A -> B -> C is natural.
When you write the program, you definitely write it as A->B->C.
Question is: what's your habit to document the precedence relationship between
A and C?
In a 200-line code, it will never be a problem. But when you work in a project
with 10~100 classes, each with 100 ~ 3000 lines of code. No good
documentation could cost heavily.
Example: when you

m*t2005-09-02 07:09

2 楼

If A should run before C is part of the logic flow, shouldn't you
have some _code_ capturing/enforcing it, instead of just documenting
it?
I would also rely heavily on rigrous testing, which always goes
hand in hand with active refactoring. "A has run" can be a precondition
for C's test cases.
Also, it would never hurt to throw in a couple of asserts at
the beginning of C if it's so important.
While it certainly needs to be well documented, documentation, by
its nature, is explanatary rather th

【在 g**********y 的大作中提到】

: In a program, there are three blocks, A, B, C.
: A must run before C, because C will change some data A depends on.
: In logic flow, A -> B -> C is natural.
: When you write the program, you definitely write it as A->B->C.
: Question is: what's your habit to document the precedence relationship between
: A and C?
: In a 200-line code, it will never be a problem. But when you work in a project
: with 10~100 classes, each with 100 ~ 3000 lines of code. No good
: documentation could cost heavily.
: Example: when you

g*y2005-09-02 07:09

3 楼

How would you write code to enforcing this logic --
A depends on XML Document object "doc" be untouched;
C will modify some nodes within "doc"
so now A should run before C
After refactoring, A become A1 + A2 + A3, actually, only A2 needs "doc" be
untouched.
And C become C1 + C2, only C2 will modify "doc".
So now, A1, A3, C1's running order is not important any more. But A2 needs to
run before C2.
I find this kind of situation happens a lot when working in a huge project.
Especially some code is

m*t2005-09-02 07:09

4 楼

Maybe I didn't really understand your scenario - don't you have to
have some code that calls A and then calls C?

【在 g**********y 的大作中提到】

: How would you write code to enforcing this logic --
: A depends on XML Document object "doc" be untouched;
: C will modify some nodes within "doc"
: so now A should run before C
: After refactoring, A become A1 + A2 + A3, actually, only A2 needs "doc" be
: untouched.
: And C become C1 + C2, only C2 will modify "doc".
: So now, A1, A3, C1's running order is not important any more. But A2 needs to
: run before C2.
: I find this kind of situation happens a lot when working in a huge project.

g*y2005-09-02 07:09

5 楼

A and C could be either function or just a block of code within a function.
Without losing generality, let's discuss about function --
{
org.dom4j.Element target;
// For all subnodes begin with "NodeDef_", add attribute
A(target);
...
// For all subnodes begin with "NodeDef_" and has "serial" attribute,
// change their name to "BusinessLogic_"
C(target);
}
you see, if the program is small, you can easily notice that A should be call
before C. However, when project grows, A a

【在 m******t 的大作中提到】

:
: Maybe I didn't really understand your scenario - don't you have to
: have some code that calls A and then calls C?

m*t2005-09-02 07:09

6 楼

call
Hmm, refactoring does not change logic flow, right? Say, even you
split C to C1, C2, and C3. What used to be:
C(target);
would simply be replaced with:
C1(target);
C2(target);
C3(target);
I see your point in general. I guess I would still rely on regression testing
to ensure the logic isn't changed. In this case, C doesn't really
require A to be run before itself, because it doesn't really rely on
anything A puts in target. It's the logic block that uses A and C needs
to be regression test

【在 g**********y 的大作中提到】

: A and C could be either function or just a block of code within a function.
: Without losing generality, let's discuss about function --
: {
: org.dom4j.Element target;
: // For all subnodes begin with "NodeDef_", add attribute
: A(target);
: ...
: // For all subnodes begin with "NodeDef_" and has "serial" attribute,
: // change their name to "BusinessLogic_"
: C(target);

g*y2005-09-02 07:09

7 楼

This would be the ideal case :-) But in our project, a likely case would be:
C3 needs to go ahead of A, because some new responsibilities are assign to it.
If I NOTICE A2 -> C2 relationship during code change, I know that C3 -> A1 ->
A2 -> C1 -> C2 is the flow I should go. Instead, a lot of times, because
lacking of good and easy way to document this, I fail to see this. As a purist
, I put C1 -> C2 -> C3 -> A1 -> A2 in code, because keeping C1->C2->C3 "looks"
good.
Mock object is an interestin

【在 m******t 的大作中提到】

:
: call
: Hmm, refactoring does not change logic flow, right? Say, even you
: split C to C1, C2, and C3. What used to be:
: C(target);
: would simply be replaced with:
: C1(target);
: C2(target);
: C3(target);
: I see your point in general. I guess I would still rely on regression testing