I see your point. You've picked up on a bias in my experience towards cohesive, self-organising teams, who practice pair programming. I was trying to distinguish organisation from team: if I ship a library jar to be used by the developer sat six feet away in the office, if she's not on my team, there should be API documentation. You're right it's a different scenario where say you have satellite developers working halfway across the globe. In your scenario, it still sounds like comments are a smell, but it's the organisation that's stinky, not just the codebase :)
On 16 April 2013 09:52, Fabrizio Giudici <[email protected]>wrote: > 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 <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.
