How to communicate software design efficiently between developers?

Question

Recently I've come to understand that a serious problem at my workplace is the lack of communication between developers. It's odd, because we're a totally open sort of organization. Everyone can go to everyone and ask whatever they need and communication is hardly regulated at all. And yet it doesn't happen by itself...

The kind of lack that I feel most keenly myself is between me (the architect of the system, more or less) and the rest of the developers (which usually work on a piece of required functionality, not the framework). Whenever I create some component or a naming convention or whatever... there's no way I can make it known to all the people who might need to know this. At most I tell it in person to the fellow who asked me for it, but that's about it.

As a result, wheels get reinvented, there are hardly any conventions in the code (mostly evolved from copy-pasting), occasional cargo-cult coding, etc. I try to clean it up whenever I get the opportunity, but with workload being as large as it is, there are rarely such chances. :(

I'm not really sure how to solve this. I could try and document all the stuff that has been created (probably would take at least a week - difficult to budget that much time) in our internal wiki, but who ever reads such places regularly for news? And how would you find if something that you need has already been implemented somewhere?

What do other people do to avoid this pitfall? What methods have shown themselves as efficient?

Answer 1

I use two things - my voice and a whiteboard.

I mean, as much as developers hate meetings, you do need to work as a team. Standups are a great time to talk about new stuff you're doing in code (and to ask if something already exists). For big things, the sprint planning meeting is a good time for the entire team to provide input to the design, so everyone knows what is going on. And the sprint demo meeting is a good time to go into short detail about how the design has changed since the beginning of the sprint. In my experience, a whiteboard is the best tool for communicating that design amongst developers. Too few are proficient enough at reading code, and nobody reads (quickly obsolete) documentation.

And for particularly big/complex/subtle things, you'll likely need to have a dedicated meeting to disseminate that info.

Code reviews can help be a last line of defense against duplicated effort or misuse/mis-modification of code. But they catch things after all of the work is done. By having good teamwork, you prevent the wasted work from being done altogether.

Don't use agile/scrum? First, my condolences. Second, the premise still holds. You need to talk as a team - daily for little things. And you need to coordinate the bigger things periodically so that you work as a team.

Answer 2

There is no simple answer.

Big pictures put on walls can help. something like the 4C diagrams (Context, Container, Component, Class) http://static.codingthearchitecture.com/c4.pdf (though class is probably too much detail)

These can help orientate people in the code, and understand what exists.

Code reviews can help spread good practices, but doing them well is an art. The reviewee should not feel put upon, and there should (mostly) not be a single gatekeeper to the repository (because of the hit-by-a-bus problem if no other)

Other than that, standups and card boards are methods for knowledge share within the team, and a good engaged team that wants to better itself is pretty key to the whole endeavour!

Answer 3

I could try and document all the stuff that has been created…

Gotta start somewhere.

…who ever reads such places regularly for news?

Then use email to notify of changes. Do keep the SNR low.

You'll need to get people behind changes (including management), then make them aware of the changes as they are adopted. You may want their input on some changes. Otherwise, just float them by in an email/update. For more complex topics, take a few minutes to explain and Q+A not long after it's been floated.

And how would you find if something that you need has already been implemented somewhere?

Code reviews would be a good start. If people are still not reusing code, you should get in at earlier stages (i.e. before code is written).

As a result, wheels get reinvented, there are hardly any conventions in the code…

That's the hard part. Nobody wants to take the initiative. My typical approach is to perform the change myself, float, discuss if needed, push, then enforce (tool-permitting).

So if it is coding conventions:

• do a dry run of the next important change on your todo list
• if that succeeds, float the change to the engineers
• if there are questions/concerns, detail the case for the change in email or meeting
• push
• enforce (tool-permitting)

That's how I usually do it, anyway. Sometimes larger tasks are divided.

Answer 4

The simplest answer is code reviews (and by code reviews, I really mean "everything related to code changes including the code itself). Obviously this means you'll have to have documentation.

I know places where people are hacking away all over the place, last place my mate worked at every time he came to fix a bug he'd grab the latest code and .. it'd have changed. One team would put changes in this direction, and another team would put changes in a different direction. Sometimes the teams changed direction all by themselves and you ended up with pure chaos where nothing got done to the product, but there was constant and intense code changes.

This is where you need some form of non-developer type change control. If you implement a system where changes are made in a controlled way, and by that I mean anyone can change something, its just that they need some reason to do it and some form of authorisation that its a good thing to progress.

So you can mandate that no change gets applied unless its in response to a change ticket. (anyone can create a ticket describing a problem that needs changing, of course) but these tickets then get assigned to a person or team by someone in charge of product direction - a business analyst or technical design authority or even a team get-together. What's important is that the change gets done in a non-individual way.

Once that is taken care of, someone will go and make changes and then you get them reviewed. This means someone else sees the code but also the ticket changes and documentation. So if you want to change your DB access system, fine... but you need to describe what it is, why it was changed, and how it works now. Without such documentation the change fails its review. Afterwards you can implement internal 'training' such as brown bags or code dojos to ensure the rest of the team gets informed.

---

Some people will resist this, but they tend to be the ones who churn code constantly, "cutting code" rather than "working on the product". This is an important distinction to make, as developers we can all get caught up in the concept that the code is what's important - its not. The product you're building is what's important and that is much more than just code.

The documentation doesn't have to be extensive, just enough to tell someone else what you've done or how it works. It can be a wiki or even just notes on the tickets - as tickets get old, they'll fade from view and the documentation with them, but this is ok as it means only relevant, current docs gets kept. Alternatively you can have a wiki of components, architecture and usage and that gets kept up to date as part of each code change. Or (my preference) is to store all your technical documentation alongside the code as text documents in a markup format that is built into html by the build server and presented on a web server - so anyone can see the current documentation which is easily updated when code is updated.

A last resort is to get an architecture team who has the responsibility to document the system, but they will also have the power to prevent any changes being made unless the documentation is updated first - many looser teams may not like this more restrictive approach, but if they cannot make it work using my suggestions then this is the system that would then have to be implemented.

Answer 5

There are (at least) two issues hidden in this common problem. The first is having a process that ensures that the appropriate communications are taking place, and the second is ensuring that developers actually follow the process - who are often under stress to deliver, and excited about writing code, driven by ego (often in a good way) etc.

The latter, I think, is often easier to achieve in practice that the former: separate the development of deployment (final integration) tests from the people responsible for coding, and do not accept any code into master branch until it passes all tests. Then, regardless of how much or little developers listen to, or follow, the communication process, any changes they make will have no impact on deployed code if it breaks the existing tests. If the tests are a true expression of all requirements (functional and non-functional) - including testing that new functionality isn't added without test confirmation - then this process enforces communication because otherwise a developer's code never goes anywhere! Your minimum job is then to communicate any new requirements to the test writers and ensure that they are implemented first.

The former - i.e. the actual communication process can then develop over time. Initially the use of the quality gate of full integration testing talked about above before commits to master are allowed will force people to come to you to ask about functionality and requirements etc. or nobody's code will ever get deployed and devs are motivated by deployment. You could then start to work with appropriate mechanisms for communication e.g. scrum meetings, or collaboration tools like Trello, or email lists, or code reviews, or daily requirement user story discussion meetings or whatever works for your structure of teams.

Put the independent deployment quality gate in place first and the rest will, eventually, follow.

Answer 6

For teams doing OO design and implementation, part of the communication should be a shared understanding of the problem space, and typical tools used to solve those problems.

The notion of design patterns was created very specifically to create a shared vocabulary that can be used as a short-hand when talking about the problem spaces.

I don't mean using design patterns as a way to extend meeting times with tiresome "so and so isn't the xyzzy pattern!" arguments. Rather, instead of having to discuss at length some specific implementation, design patterns allow us to discuss the bigger picture and how the pieces fit together.

Answer 7

This is where DevOps comes into play. It actually tears down silos between Developers and IT Infrastructure people. So, every one knows what's happening in a project. No one is left behind.

For you solution, try to implement DevOps culture in your organization.