File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Agile and Other Processes and the fly likes Implementation Patterns - Communicating through code? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "Implementation Patterns - Communicating through code?" Watch "Implementation Patterns - Communicating through code?" New topic
Author

Implementation Patterns - Communicating through code?

Darya Akbari
Ranch Hand

Joined: Aug 21, 2004
Posts: 1855
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?


SCJP, SCJD, SCWCD, SCBCD
Lasse Koskela
author
Sheriff

Joined: Jan 23, 2002
Posts: 11962
    
    5
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.


Author of Test Driven (2007) and Effective Unit Testing (2013) [Blog] [HowToAskQuestionsOnJavaRanch]
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
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?


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Darya Akbari
Ranch Hand

Joined: Aug 21, 2004
Posts: 1855
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

Joined: Dec 16, 2003
Posts: 975
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


"Eppur si muove!"
Darya Akbari
Ranch Hand

Joined: Aug 21, 2004
Posts: 1855
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

Joined: Jul 11, 2001
Posts: 14112
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

Joined: Nov 07, 2003
Posts: 45
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


Author of <a href="http://www.amazon.com/exec/obidos/ASIN/0596007434/ref=jranch-20" target="_blank" rel="nofollow">JUnit Pocket Guide</a>
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Implementation Patterns - Communicating through code?
 
Similar Threads
So many patterns, what is Implementation Patterns for?
Language
Code puzzling me
Implementation Patterns - Things I missed
WA #1.....word association