On Tue, 16 Apr 2013 10:10:13 +0200, Graham Allan <[email protected]>
wrote:
API vs Inline comments are a good line to divide across, but I suggest a
different distinction: whether the audience is in your team or not.
The difference between withing and outside of the team can be useless in
some contexts. It's ok when there's a carefully build team, with low
turnover. But often there's not such a thing, and in this case you should
comment for your co-workers as they weren't co-workers. Also consider the
case in which a large corporate is partitioned in "islands", where you can
talk of a cohese team, but just one per island. Often they deeply differ
in knowledge of the technology and processes. Most of the produced
software stays inside the original island, but often it "leaks" outside.
Even in this case, while in the same corporate, you should comment as it
is wasn't the case.
I'm following this thread and reading things that I second, but most of
the discussion about commenting depends on details on how the team has
been built, maintained, etc... A theme that has not been dealt (unless
I've lost something) and that it's very important and hard to manage is
the mapping of business rules into code. I see corporates where business
rules are very complex (I'm not in the position of analyzing them, because
it's not my business, but often they are overcomplex), but at the same
time well understood by a restricted bunch of people who are not
developers, or anyway are not OO developers. This often get translated
into overcomplex code, especially when you need optimizations (people who
define business rules usually don't deal with optimization). Optimization
is sometimes dealt "internally" by developers, other times by means of
ad-hoc slightly changes of the business rules, with the agreement of
business people. The result is that you have a sort of hybrid territory,
in which you have artifacts that must be directly consumed by developers,
but at the same time validated by business people, unfortunately the two
groups of people speak different languages. This area is extremely hard to
document - in fact, often this stuff is "maintained" by "oral tradition".
Sure, you can do a lot to improve things: tests, as usual, are good not
only for developing but also to document business rules, and use DSL that
can be at the same time consumed by programmers and directly validated by
business people, but in the end I expect a good deal of inline comments
here.
--
Fabrizio Giudici - Java Architect @ Tidalwave s.a.s.
"We make Java work. Everywhere."
http://tidalwave.it/fabrizio/blog - [email protected]
--
You received this message because you are subscribed to the Google Groups "Java
Posse" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/javaposse?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
