Home/ Questions/Q 132565
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-05-11T06:16:58+00:00

I am writing an architecture and design document for software development at our company,

  • 0

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’?

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

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

    • 0