• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Implementation Patterns - Communicating through code?

 
Darya Akbari
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Kent,

I've read somewhere that these implementation patterns are about developers communicating through code. On the extreme that means that you don't use comments in your code.

Since I see software development as a social process, I find this approach unsocial to your team. Leaving them with that wisdom that code speaks for itself doesn't help a lot.

My experience is that this explanation often comes from people who create spaghetti code on the fly. The pain start when your code is maintained by others who have to step through tons of spaghetti code.

Why not using a tiny documentation giving an overview of your model and describing the concept of your module?
 
Lasse Koskela
author
Sheriff
Posts: 11962
5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Darya Akbari:
Since I see software development as a social process, I find [not using comments in your code] unsocial to your team. Leaving them with that wisdom that code speaks for itself doesn't help a lot.

My experience is that this explanation often comes from people who create spaghetti code on the fly. The pain start when your code is maintained by others who have to step through tons of spaghetti code.

I've seen a lot of different teams working as a consultant and I rarely see good comments. In fact, most of the time the comments seem to be not just useless but downright false with the comment saying the opposite of what the code actually does. Therefore, as a rule of thumb, I always read the code, too.
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I didn't get the impression that Kent's message is "code speaks for itself, forget about documentation."

Rather what I hear him say is "I work hard on making my code speak for itself as much as possible. Here is what I've learned in the process. Hope you find it to be valuable, too."

Personally, I find that I often can replace a comment by making the code itself more communicative. I don't *always* find a way to do that, though, so some I also leave some comments in the code. And I certainly see value in some high level diagrams.

Does that sound reasonable?
 
Darya Akbari
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Think of Java SE and Java EE without any Javadoc :roll: . My experience is that code w/o Javadoc and high level diagrams is damaging the team spirit. Don't forget that we are really in a social process when creating software. You normally work in a team of more than only yourself. Think about the waste of time others need to step through each line of code. It's a huge waste of time.
 
Gian Franco
blacksmith
Ranch Hand
Posts: 979
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Darya Akbari:
Think of Java SE and Java EE without any Javadoc :roll: . My experience is that code w/o Javadoc and high level diagrams is damaging the team spirit. Don't forget that we are really in a social process when creating software. You normally work in a team of more than only yourself. Think about the waste of time others need to step through each line of code. It's a huge waste of time.


I think it's all about the granularity of the comments.

Javadoc is essential to explain the API of your code, and here I remember Joshua Bloch's lesson of considering all the code you write as being written as part of an API (forgive me for this simplification he of course explains it much better, check out Google Techtalks)

Comments that are used to explain code constructs which would otherwise be too criptic are, as Martin Fowler says, smells that should be refactored.

I think, correct me if I'm wrong, that Kent Beck considers 'code communication' as a principle that embraces both above mentioned practices.

Greetings,

Gian
 
Darya Akbari
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Gian Franco:


I think it's all about the granularity of the comments.

Javadoc is essential to explain the API of your code, and here I remember Joshua Bloch's lesson of considering all the code you write as being written as part of an API (forgive me for this simplification he of course explains it much better, check out Google Techtalks)

Comments that are used to explain code constructs which would otherwise be too criptic are, as Martin Fowler says, smells that should be refactored.

I think, correct me if I'm wrong, that Kent Beck considers 'code communication' as a principle that embraces both above mentioned practices.

Greetings,

Gian


I leave that for Kent to comment.
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Darya Akbari:
Think of Java SE and Java EE without any Javadoc :roll: . My experience is that code w/o Javadoc and high level diagrams is damaging the team spirit. Don't forget that we are really in a social process when creating software. You normally work in a team of more than only yourself. Think about the waste of time others need to step through each line of code. It's a huge waste of time.


Yes, I work in a team of 8 developers. And we write near to no javadoc for ourselves. A very well designed API plus unit tests plus working in the same room plus design sessions on the white board plus some pair programming seems to work best for us.
 
Kent Beck
author
Ranch Hand
Posts: 45
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Darya,

I recommend you read the book before concluding what's in it. I make the case for method comments there, although in some cases I find other techniques to be more effective for communication. The overall responsibility is clear: programmers are responsible for communicating with other programmers.

Regards,

Kent Beck
Three Rivers Institute
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic