software archaeology

[Michael Easter]

I enjoyed Episode 338, esp. near the 19:30 mark where someone (?)
referred to software archaeology as the main challenge of code
maintenance.

He asks about making original intent more explicit in code, wikis,
etc.

My question: why not use video? Any viewer of YouTube knows that
people will record anything imaginable, outside of the office. The
technology is easy and powerful.

Michael Easter

ps. I have a longer piece on my blog, but this is the gist of it.

[Steven Herod]

Agreed, I've often thought about recording walkthroughs of code or
project introductions, but most people seem to recoil at the
thought...

[Christian Catchpole]

Just don't mention the #nopants up front.

[Vince O'Sullivan]

On Feb 1, 2:20 am, Michael Easter <codeto...@gmail.com> wrote:
> My question: why not use video?

If you can't get people to comment their code, I doubt you'll get them
to video it.

[Ricky Clarkson]

I only comment bad code.

> --
> You received this message because you are subscribed to the Google Groups "The Java Posse" group.
> To post to this group, send email to java...@googlegroups.com.
> To unsubscribe from this group, send email to javaposse+...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/javaposse?hl=en.
>
>

[Michael Easter]

I am thinking more of a high-level architecture overview by the team
lead. IMO, a 1-hour whiteboard talk, done every 4-6 months, would be
of genuine value.

It wouldn't help with specific corners of the code, but it would help
to understand the culture.

In a comment, Alex Miller mentions that Terracotta records design
reviews (though they aren't viewed often) -- http://bit.ly/eoN1R4

[Cédric Beust ♔]

On Tue, Feb 1, 2011 at 1:30 AM, Ricky Clarkson <ricky.c...@gmail.com> wrote:

I only comment bad code.

I don't comment bad code, I fix it. Then I comment it.

--
Cédric

[Ricky Clarkson]

Sometimes you may leave a hack in place that works but is dodgy, then
when you know how to remove it, go back and remove it. In the
meantime, a comment is useful.

2011/2/1 Cédric Beust ♔ <ced...@beust.com>:

[Vineet Sinha]

We have been thinking about this a fair bit. My thought is that asking for videos from development teams might just be too hard - teams don't comment/document enough often (or more accurately don't necessarily know what is worth documenting). So what if developers could easy get to architectural overviews and have an easy ability to save/share it, so that team members could comment on them and request for more such architectural descriptions.

Do you think that would meet similar needs? And have a collaborative atmosphere do help reinforce the need to build such 'documentation'?

On a side note: While we have built the above for a couple of companies, we are trying to do something similar to Open Source projects as well. This site is not yet ready, but we would love to hear thoughts on this. See examples for the Lucene project: http://www.codemaps.org/s/Lucene_API and http://www.codemaps.org/s/Lucene_Core. (And if you are working on an open source project and want free licenses for such architectural documentation, feel free to drop me a note).

Regards,

Vineet

--

Founder, Architexa - www.architexa.com
Understand & Document Code In Seconds

vin...@architexa.com :: 617.818.0548

[Matthew Farwell]

I only comment code that needs commenting, for a particular value of 'need'.

2011/2/1 Ricky Clarkson <ricky.c...@gmail.com>

[Reinier Zwitserloot]

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).

[Vineet Sinha]

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)

[Michael Easter]

Vineet,

> videos from development teams might just be too hard - teams don't
> comment/document enough often (or more accurately don't necessarily know
> what is worth documenting). So what if developers could easy get to

FWIW, I wasn't originally thinking that individual developers would
create videos. More along the lines of a tech lead recording for an
hour per release. Super-high level stuff.

> what is worth documenting). So what if developers could easy get to
> architectural overviews and have an easy ability to save/share it, so that

On the podcast, the JR attendee entertained questions like "can we
change the wiki? the code?". He seems to hint at a more formal way to
bake-in these kinds of ideas. I am inherently skeptical of this at a
code-level and even a tool level, when such massive technology (that
is, consumer video) already exists.

That said, it is undeniable that anything that truly facilitates
communication is useful.

re: Lucene project. I will write more offline (since this involves
commercial software), but those diagrams look interesting to me. I
think using an open-source project like Lucene is a clever idea.

[Michael Easter]

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".

> > javaposse+...@googlegroups.com<javaposse%2Bunsu...@googlegroups.com>
> > .

[dun...@oneeyedmen.com]

WRT video documentation - I have tried a trick that I think I learned
from one of Alistair Cockburn's books.

Give an hour-long talk on the topic (architecture, design, whatever)
to several of your target audience (other devs, customers etc) and
record it. Then have a Q&A session with the audience, also videoed.
This way your talk will be addressed to real people, and anything that
you miss and isn't obvious should be covered in questions afterwards.

I've only done this once - as the handover for a project that was
being mothballed, but it seemed to work well.

Duncan

[Vineet Sinha]

I am actually a lot more of a proponent of videos for one-offs that doing something on a recurring basis. But there is often just so much that needs to be covered that a single 1-3 hours talk has never been enough.

FWIW, I wasn't originally thinking that individual developers would
create videos. More along the lines of a tech lead recording for an
hour per release. Super-high level stuff.

Michael, I understand you were talking about tech leads, but my worry about doing videos on a recurring basis is more to do with the effort involved in producing it - which is why I am suggesting individual developers doing a little something (and somehow giving them an incentive to do the work).

re: Lucene project. I will write more offline (since this involves
commercial software), but those diagrams look interesting to me. I
think using an open-source project like Lucene is a clever idea.

Do feel free to send feedback for the commercial side of things, but we are beginning to focus more on the needs of the open source community  (and users of open source projects). 

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".

Great point. Perhaps we need some kind of a chat / IM like lightweight discussion tool as opposed to something  that (to me atleast) feels heavier like videos. Ofcourse, making such chat logs easily available with the code/project is another challenge.

- Vineet (Founder, Architexa)