Document key ingredients of good software development?

Question

I am writing an architecture and design document for software development at our company, that will contain the rules and guidelines for developers to follow. It is targeted at J2EE web applications, but I constantly keep mentioning the same basic 'ingredients' (for lack of a better word, and to avoid buzzwords) to introduce and defend certain choices.

These are the following:

• Abstraction: focusing on “what” instead of “how”.
• Encapsulation: hiding the “how”.
• Separation of concerns: division into distinct non-overlapping structures.
• Low coupling and high cohesion: making any divisions meaningful.

The advantage of including them would be that when the document doesn't mention something specifically, it is easy to point to these key ingredients so they serve as a kind of catch-all.

The disadvantage would be reactions like "Yeah, great, but I just need to know what class I need to extend to implement this controller."

Am I right in identifying and discussing these general issues first, or should I just 'stick to the point'?

Answer 1

Just place a copy of Code Complete 2 in your library and point your devs at that.

Answer 2

Yeah, I did that once. Didn't help.

I think software development is hard, and there is no way that listing these four concepts, no matter how important, will improve the quality of the code in your organization. What you really need is building up knowledge and experience. If I had to make up a list, it would contain:

• Accept that the rule 0 is to produce better code. If a single coders does not agree to this, you may be in trouble.
• Do code reviews. That will fix most of the problems you list, and has tons of other advantages.
• Communicate about what you're doing - the more often, the better. Put your ego aside and don't hesitate to ask your senior colleagues for advice. If you're a senior developer, listen to your younger peers, often more in tune with the latest techs, ideas, practices and idioms.
• Respect your code base. Every single line of code is important and must be right.

All of these are human factors. I think that's where to road to better programming in an organization starts.

Answer 3

This is something which needs to be taught and explained.

Some people can learn it from books but the books need to be well written, no offence but most people aren't actually that good at this so consider using an existing well reviewed book instead (++ for code complete) perhaps with some indications on which chapters are relevant.

Some people can't (or won't) learn from books. If they can't then you need to spot these people and help them if they are worth the investment of your time. If they won't consider firing them since they are simply wasting your time.

These concepts are quite ephemeral till you actually use them (better still don't use them, realise later how much pain it caused not doing it right the first time and learn from your mistake). Simply restating the existing literature but worse is not a productive use of your time IMO.

Answer 4

I was in a similar boat re: writing documentation for the developers. Face reality, they won't read it or if they do they won't apply the principles. You need to take the lead and run small training sessions to show them what you mean / looking for. I did this with great success. Little 1-2 hour sessions with the senior devs. We looked at good code, bad code and talked through why it was good and bad.

The documentation can serve as a good backup but face to face learning can never be beaten.

Answer 5

What you mention should be obvious to any developer but they tend to forget that as soon as they start typing. From my experience, these guidelines will help you improve:

• Write automatic unit tests
• Have an automatic build system which builds the whole product ready for production overnight
• Aim for a code coverage in the tests between 80% and 90%

Important note: these are guidelines, not rules. Guidelines work in a changing environment while rules don't.

Reasoning: When you write a test, you need to abstract your classes. You automatically begin to hide in inner details because anything else would make your tests more complex.

The nightly build system will help you notice bugs within 24h or less. If you find something broken in morning on which you were working yesterday, chances are you can still remember what you were working on. This will make it much easier to find and fix the problem.

As for the code coverage: You will need 20% of the time to write tests that cover 80% of your code and 80% to write tests for the next 10% and 1000% of the time (ten times) to get 100% (or rather 99.999%). If you actually get that far, every code change will break so many tests that you will stop testing. In the end, 80-90% coverage will get you much better ROI.

I also suggest to read this: Thoughts on Developer Testing

Answer 6

In my opinion your question is focused too much on source code. The source code is the end result of a development process. I think you should also focus on the -process-, i.e. on HOW the software is being developed.

• What are the activities in the development process, and what stages and milestones can be defined?
• Who are involved in the development process and what are their roles?
• How much time is required for the different activities and what will be the release interval?
• What are the final deliveries of the different activities, e.g. design documents, diagrams, presentations, manuals, source code, binaries and so on?
• Who is responsible for each stage?

Also, for each of the development activities some instruments can be specified to support the development team such as:

• Weekly progress meetings
• Presentation and debate of design ideas
• Issue lists and bug trackers
• Version management
• Checklists
• etc.

My experience is that a structured development process will eventually also contribute to the quality of the source code. For example, when developers regularly present their work to the whole development team, they will get constructive feedback and learn from their colleagues. A developer who better understands the concepts of OO (abstraction, separation of concerns, inheritance etc.) gets the opportunity to transfer his/her knowledge to his/her colleagues.