re: architecture comments. I agree that there is always a sense of scope: reviewing and understanding small scope (e.g. a class or a method) is relatively easy. The larger scope is difficult.
In my experience, teams talk in terms of layers, and the good ones are careful to maintain a sense of integrity across layers. As these layers become fine-grained (imagine being on the server, but splitting hairs between a service and a persistence layer), "team culture" becomes intuitive for veterans but difficult for newbies and maintainers. As I think about it, the real problem is candid architecture comments. It is hard to capture, via a diagram or doc, the following: "Our client layer is tight. The server layer is mostly ok, but because of X,Y,Z, our domain model is split between legacy objects and new clean POJOs. The legacy objects have a ton of dependencies on A,B,C but we hope to remove them over the next few releases". On Feb 4, 11:32 am, Vineet Sinha <vin...@architexa.com> wrote: > I think the discussion here is more than just code comments - it is about > architecture comments. Code comments help, so shouldn't architecture > comments of some form help as well. Yes, that means figuring out what > architecture comments are, and what you can do to have them not be a burden > - but I am sure we as developers can hack together a few solutions that > help. > > I do agree that most well written code doesn't need comments. But, how do > you know your code is well belongs to that category? With developers > spending huge amounts of time understanding code and our own biases that our > own code is easy to understand, we owe it the rest of our teams to think > twice about commenting. I know code review helps here, but if we are > thinking a little higher level - we need to do architectural review of some > sort. > > Yes, comments cannot be unit tested - but shouldn't we instead ask for tools > that let us do that in some form? Perhaps forcing you to update comments, > when you change relevant pieces of code - or otherwise reducing your team > karma. And ofcourse, on the architecture side - perhaps somehow connecting > tools like JDepends to architectural comments. > > (And I am also a big fan of clean version control trees.) > > I am not trying to be some kind of architecture fanatic, but if we as > developers don't talk about what a good architectural tool will be that > meets our needs then we many never get helpful tools for us - from the open > source community, academia, startups, or even larger companies. > > - Vineet (Founder, Architexa) > > On Fri, Feb 4, 2011 at 4:17 AM, Reinier Zwitserloot <reini...@gmail.com>wrote: > > > No, I fix bad code, then I don't comment it, because the vast majority of > > code that fits the 'this is within 10% of as good as it could be written' > > doesn't need comments. > > > Comments cannot be unit tested and thus can flow into a buggy (i.e. no > > longer relevant or even actively misleading) state, and are tedious to keep > > up to date even if you do realize you're making updates that don't mesh with > > what the comments say. > > > Of course, for the few cases where there's no way to let the code speak for > > itself, by all means comment. i.e. you tried something that seems simpler or > > a more logical way to do it, but there's an easy-to-miss problem doing it > > that way. > > > Another aspect of source history delving that's important to _try_ to get > > your developers to do right is keeping the version control tree clean. This > > is perhaps a YMMV thing, but, I _really_ like it when the commit history is > > mostly devoid of superfluous merges and each individual commit is part of a > > sensible whole and has a decent commit message. This means I use git, and > > this means I'll be extensively rebasing a local branch into a sane whole > > before I rebase it on top of master. Now a git blame on a line that makes me > > go "WTF is this?!?" leads me to the commit and the message there usually > > explains to me exactly why its needed (or, better yet, makes me understand > > the brainfart that caused it, so that I can fix it secure in the knowledge > > that I'm in fact smarter than the original commit, instead of dumber, i.e. > > overseeing some nuance). > > > -- > > You received this message because you are subscribed to the Google Groups > > "The Java Posse" group. > > To post to this group, send email to javaposse@googlegroups.com. > > To unsubscribe from this group, send email to > > javaposse+unsubscr...@googlegroups.com<javaposse%2bunsubscr...@googlegroups.com> > > . > > For more options, visit this group at > >http://groups.google.com/group/javaposse?hl=en. -- You received this message because you are subscribed to the Google Groups "The Java Posse" group. To post to this group, send email to javaposse@googlegroups.com. To unsubscribe from this group, send email to javaposse+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/javaposse?hl=en.
