Of course, to some degree, it depends but there's a good range to be at - the ideal is probably 40-60% and that's an average over the course of a year - during a design phase it's probably 10% coding (prototyping / proof of concept), during full-on development maybe 75% etc.
Once you go less that 20-25% coding you are in danger of becoming an "Astronaut Architect"
(thanks Joel!). If you go more than 75-80% coding there's a danger you won't see the forest for the trees - you get too tied into your own development and you're not really able to help junior developers on your team.
What do you think? In your experience with other Architects whats a good range or AS an architect yourself where do you sit in that range and where would you like to be?
6/15/06
Why documentation matters - intent and abstraction
OK so I know I'm swimming against the tide on this one - so let's just say it "I'm in favor of documentation for software". Eek! Yowza!
Now I don't mean docs for users (although that's important) I mean MS Word documents with nice box and UML diagrams for developers - not just javadoc.
I'd say of all the developers I've worked with, probably 80% dislike (if not disdain) documentation and probably 70% don't even see a need for it. Maybe a little javadoc but hey the signature
"public void doStuff(Object o) throws Exception"
is 100% clear right? WRONG!
For managers the percentages are a little better (60%/50% like documentation) but it is not by much and mostly its because they want to know exactly what's going on and *NEED* documentation.
I see several aspects of documentation as very important and useful to developers primarily and to the enterprise at large secondarily:
1) New Developers / Testers on your team
So you show some 250 kLOC to a new senior engineer, give them a sparse functional spec and ask them to go coding some new feature!?!?! -Personally, I think the learning curve will be huge. Which components do they need to change?
Which components do they need to ignore?
Which interfaces do they need to extend?
How do they test it?
What standards need to be followed - syntax, threading, resources etc.?
Now I'm not talking about creating a 500 page CMM tome - just, say, a 20-40 page document describing layers, the high level architecture and what components do what.
I mean it's easier to read a 20 page architecture / design doc than it is 250 kLoC!
2) Intent
OK so the code is self-documenting and debugged right? So I don't need documentation? Well no! If you've read Knuth you know that very few programs are provably correct (well not any one beyond a few hundred lines in the real world). So your code does what you want it to do? That's great, but does it do what it is *SUPPOSED* to do?
Well maybe you know (or will after more testing) but will anyone else?
More importantly what *YOU* think you need to implement and what your tech lead / architect need to implement can be very different.
Documentation can help elucidate the intent of your program.
3) Clarification
This is similar to #2 but the audience is different - it's YOU - the developer! That's why writing is useful - putting stuff down on paper removes some of the "abstract-ness" and "fuzziness" and makes things more concrete - that is it makes things seem more clearly right (or clearly wrong) or clearly incomplete. OK writing can also make clear things fuzzy too but it helps, excuse the pun, keep folks on the same page.
4) Abstraction
Remember 7+/-2 - Miller's magic number- the guidelines of short term memory and the number of "chunks" you can think about at once? Even OOP is a nod to that - it's easier to think about discrete objects than about the entirety of the myriad attributes and methods.
But say we have 15-20+ objects (and probably more) how do you begin to think about those?
At some point with systems bigger than 30-40 classes, a document has to be put together to describe the overall architecture/design at a fairly high level (layers, packages etc.) with the intent of each.
So I think documentation is important and I'm always wary or concerned when I see companies, teams or processes that "just don't DO" documentation as it's a waste of time.
Usually it's a bad smell - a sign or symptom of more serious issues.
Side note
Computer languages are advancing more and more to be closer and closer to everday English (compare Assembly to C to Java). Why? Because the code is easier to write and read? Why does code need to be easy to write *AND* read!?!?!? - So you can be sure it's doing what it's bloody well supposed to! :-) I know very few people who truly write self-documenting code (they can read it sure, but can you?) so a high level description is warranged
So what documents do I prefer and suggest people write - well there's two
#1 - The Architecture and Design document
Describe the layers, the objects, what patterns you follow and most importantly the intent - what are the layers, objects and patterns *SUPPOSED* to do. Also for decisions out of the "norm" - document *WHY* not what. For Example
Q: Why do you limit the connection pool to 3 connections
A: the legacy database tends to deadlock otherwise
So if MAX_CONNECTIONS=3 in the code that's fine - but if a new developer is on the team
and they have a performance issue - you *KNOW* the first thing they're gonna do is
bump that to 5 or 10 and waste their time and your time doing something that won't work.
#2 - The Cookbook
OK now that a developer knows what each piece does (and probably forgotten half of it by the time they reach they end) - what do they actually do with that knowledge?
What are the common extension / maintenance points and how does the developer get it done? What are good examples and what are the potholes to watch for? What tests should they run?
A cookbook can answer that.
Again I'm not a guy who *LOVES* to write nothing but documentation (think CMM - yikes!) but a 20 page document with a few UML diagrams for your 250 kLoC can be banged out in 2-3 days.
CommonCounterArg1: But applications change quite a bit over time . . .
So code changes over time and documentation starts to "rot"? Sure that happens but probably every man-month of developer effort might make a page or two of changes - and if you are changing more than that, then something was probably wrong with your original requirements or design - overall I think the gain outweighs the cost.
CommonCounterArg2: But XP abhors "Big Design Upfront" . . .
Sure it does and that probably works for a crack team of rock-solid, highly experienced developers but most teams I've seen are a mix of skills and a mix of capabilities with 15-25% turnover a year. On a team of 16 developers that means 2-4 new people *EVERY* year - just how many times do you want to explain the build process, the classes, where everything is?
As a nod to tendencies (and painful experience) I'm a big fan of diagrams - UML and others - if I see a page of nothing but text I'll tune out. So again when I say 20-30 pages - you're free to add diagrams liberally throughout as long as they help explain *what* it does, what it is *supposed* to do and *why*.
-Frank
Now I don't mean docs for users (although that's important) I mean MS Word documents with nice box and UML diagrams for developers - not just javadoc.
I'd say of all the developers I've worked with, probably 80% dislike (if not disdain) documentation and probably 70% don't even see a need for it. Maybe a little javadoc but hey the signature
"public void doStuff(Object o) throws Exception"
is 100% clear right? WRONG!
For managers the percentages are a little better (60%/50% like documentation) but it is not by much and mostly its because they want to know exactly what's going on and *NEED* documentation.
I see several aspects of documentation as very important and useful to developers primarily and to the enterprise at large secondarily:
1) New Developers / Testers on your team
So you show some 250 kLOC to a new senior engineer, give them a sparse functional spec and ask them to go coding some new feature!?!?! -Personally, I think the learning curve will be huge. Which components do they need to change?
Which components do they need to ignore?
Which interfaces do they need to extend?
How do they test it?
What standards need to be followed - syntax, threading, resources etc.?
Now I'm not talking about creating a 500 page CMM tome - just, say, a 20-40 page document describing layers, the high level architecture and what components do what.
I mean it's easier to read a 20 page architecture / design doc than it is 250 kLoC!
2) Intent
OK so the code is self-documenting and debugged right? So I don't need documentation? Well no! If you've read Knuth you know that very few programs are provably correct (well not any one beyond a few hundred lines in the real world). So your code does what you want it to do? That's great, but does it do what it is *SUPPOSED* to do?
Well maybe you know (or will after more testing) but will anyone else?
More importantly what *YOU* think you need to implement and what your tech lead / architect need to implement can be very different.
Documentation can help elucidate the intent of your program.
3) Clarification
This is similar to #2 but the audience is different - it's YOU - the developer! That's why writing is useful - putting stuff down on paper removes some of the "abstract-ness" and "fuzziness" and makes things more concrete - that is it makes things seem more clearly right (or clearly wrong) or clearly incomplete. OK writing can also make clear things fuzzy too but it helps, excuse the pun, keep folks on the same page.
4) Abstraction
Remember 7+/-2 - Miller's magic number- the guidelines of short term memory and the number of "chunks" you can think about at once? Even OOP is a nod to that - it's easier to think about discrete objects than about the entirety of the myriad attributes and methods.
But say we have 15-20+ objects (and probably more) how do you begin to think about those?
At some point with systems bigger than 30-40 classes, a document has to be put together to describe the overall architecture/design at a fairly high level (layers, packages etc.) with the intent of each.
So I think documentation is important and I'm always wary or concerned when I see companies, teams or processes that "just don't DO" documentation as it's a waste of time.
Usually it's a bad smell - a sign or symptom of more serious issues.
Side note
Computer languages are advancing more and more to be closer and closer to everday English (compare Assembly to C to Java). Why? Because the code is easier to write and read? Why does code need to be easy to write *AND* read!?!?!? - So you can be sure it's doing what it's bloody well supposed to! :-) I know very few people who truly write self-documenting code (they can read it sure, but can you?) so a high level description is warranged
So what documents do I prefer and suggest people write - well there's two
#1 - The Architecture and Design document
Describe the layers, the objects, what patterns you follow and most importantly the intent - what are the layers, objects and patterns *SUPPOSED* to do. Also for decisions out of the "norm" - document *WHY* not what. For Example
Q: Why do you limit the connection pool to 3 connections
A: the legacy database tends to deadlock otherwise
So if MAX_CONNECTIONS=3 in the code that's fine - but if a new developer is on the team
and they have a performance issue - you *KNOW* the first thing they're gonna do is
bump that to 5 or 10 and waste their time and your time doing something that won't work.
#2 - The Cookbook
OK now that a developer knows what each piece does (and probably forgotten half of it by the time they reach they end) - what do they actually do with that knowledge?
What are the common extension / maintenance points and how does the developer get it done? What are good examples and what are the potholes to watch for? What tests should they run?
A cookbook can answer that.
Again I'm not a guy who *LOVES* to write nothing but documentation (think CMM - yikes!) but a 20 page document with a few UML diagrams for your 250 kLoC can be banged out in 2-3 days.
CommonCounterArg1: But applications change quite a bit over time . . .
So code changes over time and documentation starts to "rot"? Sure that happens but probably every man-month of developer effort might make a page or two of changes - and if you are changing more than that, then something was probably wrong with your original requirements or design - overall I think the gain outweighs the cost.
CommonCounterArg2: But XP abhors "Big Design Upfront" . . .
Sure it does and that probably works for a crack team of rock-solid, highly experienced developers but most teams I've seen are a mix of skills and a mix of capabilities with 15-25% turnover a year. On a team of 16 developers that means 2-4 new people *EVERY* year - just how many times do you want to explain the build process, the classes, where everything is?
As a nod to tendencies (and painful experience) I'm a big fan of diagrams - UML and others - if I see a page of nothing but text I'll tune out. So again when I say 20-30 pages - you're free to add diagrams liberally throughout as long as they help explain *what* it does, what it is *supposed* to do and *why*.
-Frank
6/6/06
Usability - the most under-rated weapon for software architects
Here's a radical idea for software architects
"Happy users = Success"
(Happy management however - now that's a whole other kettle of fish - often happy users can convince management to be happy though)
Here's another one
"Perception is reality"
Take these two premises together and you get the following
Great application usability is a key to success.
Think about it - you might have all the functionality in the world but if it's hard to use then it might as well be nearly useless (users don't want to be taught a UI - it should be, to some degree, obvious - otherwise it's not in synch with their processes).
On the positive side think Google - simple UIs with great functionality - not too busy.
On the negative side - have you ever seen the Bloomberg trading system screens - take a look here.
Ugh - just a step above green screen - now don't get me wrong - Bloomberg (the company and the man) has made a *TON* of money off of this thing. Why? Because it has LOTS of functionality and it's data is very timely accurate (plus it locks you in but that's another thing keeping them in the $$$).
Imagine Bloomberg with a very user friendly UI - damn now that would be a cash cow!
Those UI ideas also lead into a favorite practice I love - prototypes - give them a great prototype with great usability and it generates excitement (it needs to be tempered as "you can't have it next week as there's no back-end yet")
Keys to great usability
- Understand the existing business process
- Perform analysis to streamline the process and fit it into a reasonable UI flow
- Understand user interface norms and practices e.g.
GREAT PLACES TO START
- Designing Web Usability : The Practice of Simplicity by Jakob Nielsen
- Don't Make me Think by Steve Krug
"Happy users = Success"
(Happy management however - now that's a whole other kettle of fish - often happy users can convince management to be happy though)
Here's another one
"Perception is reality"
Take these two premises together and you get the following
Great application usability is a key to success.
Think about it - you might have all the functionality in the world but if it's hard to use then it might as well be nearly useless (users don't want to be taught a UI - it should be, to some degree, obvious - otherwise it's not in synch with their processes).
On the positive side think Google - simple UIs with great functionality - not too busy.
On the negative side - have you ever seen the Bloomberg trading system screens - take a look here.
Ugh - just a step above green screen - now don't get me wrong - Bloomberg (the company and the man) has made a *TON* of money off of this thing. Why? Because it has LOTS of functionality and it's data is very timely accurate (plus it locks you in but that's another thing keeping them in the $$$).
Imagine Bloomberg with a very user friendly UI - damn now that would be a cash cow!
Those UI ideas also lead into a favorite practice I love - prototypes - give them a great prototype with great usability and it generates excitement (it needs to be tempered as "you can't have it next week as there's no back-end yet")
Keys to great usability
- Understand the existing business process
- Perform analysis to streamline the process and fit it into a reasonable UI flow
- Understand user interface norms and practices e.g.
- Don't use underlines in text - they signify HTML links (hrefs)
- Don't do navigation with drop-down boxes (it's a bad UI "smell")
- Things like the Windows Explorer, shopping cart etc. are paradigms that users know and understand
- Other paradigms - top nav, left nav, the use of tabs, the use of paging
GREAT PLACES TO START
- Designing Web Usability : The Practice of Simplicity by Jakob Nielsen
- Don't Make me Think by Steve Krug
6/1/06
Desert Island - Books
OK so this is old hat by now - what books do I think I absolutely *need*
BOOKS
1) Java Development with Ant by Hatcher & Loughran
My favorite book for my favorite tool - Ant
2) Patterns of Enterprise Application Architecture by Martin Fowler
Just tons of great ideas to everyday common issues in the OOP world
3) Software Requirements by Wiegers
Want good requirements? Start here. But hang on if I'm trapped on an island who are
my customers - OK so maybe I have a phone and/or video conference :-)
4) Rapid Development by McConnell
Too many Software developers, managers etc. I know do not know the stuff in here - it's a must have
5) Professional XML by various Wrox press authors - OK so I need a single tome on XML? Then this is it - from XML to XPATH to XSLT to Schemas / DTDs this has it all
Here's some I considered but rejected . . .
-Java in a Nutshell? No - not if I've got Javadoc. But Flanagan writes great books!
-Java Examples in a Nutshell? I can usually figure it out and anyway being trapped on a desert island I've got nothing but time
-Junit in Action - Hmmmm close but no cigar
So what about you? What tech/computer science books do you know and love and which ones do you find yourself thumbing through or reading again and again? Are any of the "classics" or popular books overrated in your opintion? Any unknown greats out there too?
BOOKS
1) Java Development with Ant by Hatcher & Loughran
My favorite book for my favorite tool - Ant
2) Patterns of Enterprise Application Architecture by Martin Fowler
Just tons of great ideas to everyday common issues in the OOP world
3) Software Requirements by Wiegers
Want good requirements? Start here. But hang on if I'm trapped on an island who are
my customers - OK so maybe I have a phone and/or video conference :-)
4) Rapid Development by McConnell
Too many Software developers, managers etc. I know do not know the stuff in here - it's a must have
5) Professional XML by various Wrox press authors - OK so I need a single tome on XML? Then this is it - from XML to XPATH to XSLT to Schemas / DTDs this has it all
Here's some I considered but rejected . . .
-Java in a Nutshell? No - not if I've got Javadoc. But Flanagan writes great books!
-Java Examples in a Nutshell? I can usually figure it out and anyway being trapped on a desert island I've got nothing but time
-Junit in Action - Hmmmm close but no cigar
So what about you? What tech/computer science books do you know and love and which ones do you find yourself thumbing through or reading again and again? Are any of the "classics" or popular books overrated in your opintion? Any unknown greats out there too?
Desert Island - Java/J2EE Libraries
OK, so in the same vein as "Desert Island - Tools" what libraries do I absolutely NEED?
LIBRARIES
1) Jakarta Commons Especially Lang, BeanUtils, Digester and Validator
2) log4j Beats the pants off of plain Commons logger and the Java logging API
3) Hibernate (or Toplink) -- Need an O/R mapping tool - Toplink is my favorite but
only comes with an Oracle App Server / DB Server license, so Hibernate is the next best thing
4) Castor - Need to map XML to Objects and back again
5) POI - Great for integration with M$ products
6) Xerces - Gotta be able to parse / create XML thingys!
7) Xalan - Nice to be able to use XSL for your multi-modal Web Site, Cell phone service on your own desert island :-)
Hmmm what else can bring it up to a nice round number of 10?
Well I'm not sure I *need* anything else so I'll leave it be!
For you what libraries do you know and love and find yourself using on almost every project? Are there any really great ones we should know more about?
Desert Island - Tools
OK so the whole "Desert Island" paradigm is about imagining you are stuck on a desert island and had to do X what are the smallest number of things you think you need to achieve X.
The concept was made popular by "Desert Island Discs" a radio show where people are effectively asked what music they can't live without?
So in this entry on Java development (why you'd be doing development while trapped on a desert island I don't know but anyway . . . . ) I talk about my top 10 favorite tools - the ones I can't live without
TOOLS
1) Ant
Simply the greatest tool developed in the last 10 years for Java - beats JUnit and Eclipse - why? There were always a few good IDEs, you can always write unit tests (without JUnit) albeit in an inconsistent way - but a cross-platform build tool that let's you automate *ANYTHING*!?!? Priceless
2) Eclipse (3.1+) of course
It's free and *HIGHLY* capable - for crying out loud it drove Borland out of the IDE business!
3) JUnit
Just plain old good practice - unit test what you wrote
4) Checkstyle
Do you really think an empty Catch block is a good idea!?!?! No - so how are you going to find it in 250kLoC - use Checkstyle baby!
5) App/Web Server: Tomcat 5.5+
Playing wait-and-see on Geronimo - usability is not great so far for Geronimo (where the hell is the JNDI?)
6) Clover
Unit testing is not much good if you're not testing most if not all of the unit :-)
Useful adjunct to Junit *IF* I was doing EJB development - a big IF.
When the heck is MockEJB gonna turn 1.0?
8) Database: Oracle
Oracle is pretty much a standard in most places now (esp. Java shops) Sybase just drowned and DB2 is so bloody hard to use. Haven't played with Derby / MySQL yet
9) Development OS: Any GUI that Eclipse runs on (usually Windows I guess)
vi / emacs just doesn't cut it for me :-)
10) Deployment OS: Linux (RHEL 3.0+)
Not as great at scale-up as Solaris but quite a bit cheaper - anyways most solutions I've seen tend to need to scale-out more so than up.
So over to you? What tools do you love? What ones are gaining popularity (Maven?) and are any losing (Jbuilder?). Are there any great tools out there just "under the radar" so to speak?
Subscribe to:
Posts (Atom)