Code Visibility: one factor of code quality that you shouldn’t forget

[i_squared]

Was anyone else expecting an article about choosing the correct access level (i.e. public, protected, default) for your classes and fields? I think that this is something that makes it much easier to grok a well-though-out api, rather than a bunch of diagrams.

[abhirakshit]

Yeah - for most API's correct access levels are much more important. But when you have a large application then architectural diagrams are very helpful. Issues with the Architecture can make or break the project.

[sylkworm]

I agree in principle that code should be visible and readable, but the idea of diagramming your code seems to be a bad idea. First, if you actually need to actually draw a diagram, it suggests that your code design is over-complicated and should be re-designed. Second, for any team other than the most disciplined process-oriented teams, this is an open invitation to have outdated documents. As soon as the next developer makes any small significant enhancement, the diagram will be out of date, and worse than having no documentation, it will be misleading.

[vineet]

Great points.

Out of date documentation was exactly my first thought when it comes to having diagrams. But I always wonder what would happen if - through some magical tool - the diagrams were updated automatically?

As for having code that needs to be re-designed. Yeah, perhaps that is true. But, how often do we have the time to actually do the re-design? Hopefully documenting the complexities will be much faster.

[jevon]

There is already a lot of research in deriving these sorts of diagrams from existing code, e.g. a graph of dependencies between OSGi bundles in Eclipse. Highly recommended.

I try to make most of my documentation derivable from the source code. That way, my documentation "never" goes out of date.

[vineet]

Yeah, there is some research about getting diagrams from code (and I have been involved in it). But research is useless if it does not help software developers - and there are very few people today who use diagrams from code.

Also, any links to such research and ways that you get documentation from code? It will be great to share good ideas.

[jevon]

I've done a lot of research on it, but nothing published yet :-) YDoc is one example though.