DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Codify the Rules You Use to Organize Your Code

We don't spend enough time thinking about how our code is organized. Think how much easier our lives and refactorings would be if we did!

Simon Brown user avatar by
Simon Brown
·
Apr. 05, 16 · Opinion
Like (10)
Save
Tweet
Share
12.98K Views

Join the DZone community and get the full member experience.

Join For Free

regular readers will already know about structurizr — a set of open source libraries to create a software architecture model as code, plus a saas product to visualize those models. having created and helped create a number of models with structurizr now, i've noticed an interesting side-effect. in the absence of architectural information being present in the code, the power of using something like structurizr to define a software architecture model using code is in extracting information algorithmically, by codifying the rules that you've ultimately used to structure your codebase.

let me give you an example. imagine you're building a web-mvc web application in java, c#, etc. and you have a tens or hundreds of controller classes, each of which uses a number of other components to implement some functionality. drawing a single diagram to visualize the static structure of the entire web application is a bad idea because it shows too much information. a better approach is to create one view per vertical slice , where there could be one vertical slice per web controller. this results in smaller, simpler diagrams like this.

a component diagram based upon a web controller

so far, so good, and this is relatively easy to do using static analysis techniques. but you'll notice this diagram includes an "authenticated user", which isn't part of the code itself. this raises the question of how the user ends up getting included on the diagram.

there are a number of options:

  • manually add the correct type of user on a case by case basis.
  • match the controller's url routing to the permitted user role (this is likely specified in configuration somewhere) and use this information to choose the appropriate type of user for each controller.
  • add machine-readable metadata (e.g. java annotations, c# attributes) to specify the user type (there are some structurizr annotations i've created to help with this).
  • codify the rules you've used to organize the controllers in your codebase.

the ability to codify the rules you've used to organize the controllers in your codebase obviously depends on how much thought you've put into doing this. for example, did you dump all of these controller classes into a single package or namespace without giving it much thought at all? or perhaps you took martin fowler's advice and modularised further , creating one package/namespace per functional area or aggregate root, for example. another possibility is that you grouped controllers together based upon whether unauthenticated users, authenticated users or other software systems are using them. organising your code well provides you with another angle to extract architectural information, because you can codify rules such as, "the anonymous user uses all controllers in the com.mycompany.mywebapp.unsecured package/namespace".

with hindsight this is fairly obvious, but we often don't put enough thought into how we organize our code, possibly because we perceive that it doesn't actually matter that much and modern ides provide powerful ways to navigate large and/or complex codebases. trying to codify the rules used to organize a codebase certainly gets you thinking, and often refactoring too.

Published at DZone with permission of Simon Brown, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • 13 Code Quality Metrics That You Must Track
  • Automated Performance Testing With ArgoCD and Iter8
  • API Design Patterns Review
  • Load Balancing Pattern

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends: