Software Architecture, Architect, and API Qualities

Software Architecture
Key Software Design Principles

Paul Rayner — How Agile Can Cripple Effective Design Work (and what to do about it)
"A good design is not one that correctly predicts the future, it's that makes adapting to the future affordable." -Venkat Subramaniam

 Good Architecture Qualities:
  • Useful, satisfies the requirements
  • Bug free given adequate effort (remember Microsoft worse is better to be first to market)
  • Responsive enough
  • Secure
  • Reliable enough 99.9, 99.999... see this and this
  • Ubiquitous/Portable access/environment
  • Robust - tolerant of faults with minimal outage and no corruption
  • Maintainable/Extensible: adequate test coverage, easy to refactor
  • Scalable: ideally horizontal scale vs. vertical
  • Implementation consistency
  • Cohesive modularity with low coupling
  • Defined layering and visibility
  • Acyclic / unidirectional dependencies
  • Convention over configuration
  • Overarching concerns are abstracted and consistent: security (authentication, authorization, auditing), monitoring, metrics, logging, persistence, transactions, exceptions, error messages, search, pagination, caching, configuration, internationalization, messaging
  • Package by feature not by layer
  • Not complex: KISS - Keep it simple, Stupid
  • No waste, nothing extra: YAGNI - You aren't going to need it
  • DRY - no/low duplication, follow Rule of Three
  • Service Statelessness
  • Microservices
  • Continuously Delivery/Deployment: enable by microservices
  • Zero-Downtime Deployment/Updates: if warranted, increases developer and testing effort
Good Architect Qualities - in no particular order
  • Passion for the craft
  • Good listener and communicator
  • Collaborates and negotiates with all stakeholders to: extract and define true requirements, create comprehensive architecture, and achieve buy-in
  • Technical knowledge
  • Leadership skills, decision maker
  • Aware of and navigates organizational politics
  • Practical: can shoot the engineer and create a shippable product timely
  • Careful: demands adequate testing and progressive deployments and/or migration to reduce risk
  • Design and programming skills
  • Business domain knowledge
  • Software Development Process/Life Cycle experience and knowledge
  • Curious: continuously explores new technologies, patterns, frameworks, tools, and best practices
  • Continues to learn and grow, attending technical conferences
  • Thorough: open-minded exploring beyond the first solutions, continually asking questions and seeking out alternatives
  • Cautious: utilizes NEW alternatives when/where appropriate: beneficial, productive, stable, mature
  • Scrutinizes costs, flexibility and maintenance of buy/COTS vs build/reinventing the wheel
  • Pragmatic: can prioritize features and create MVP when necessary
  • Grok, utilize, and communicate common well tested and understood design patterns
  • Strives to recognize all assumptions and to validate them
  • Documents assumptions and all considered alternatives with pros and cons, why certain choices were and weren't made - document for those that follow why the design is the way it is
  • Mentor: shares knowledge and experience through demos, hosting technical talks, lunch & learn, and/or teaching others one-on-one or in group settings
  • Not Pedantic, egotistical, sanctimonious, or self-righteous which inhibit collaboration & buy-in
  • Overseer: reviews and monitors that implementation adheres to the overarching design goals and not violated without good reason
  • Available to discuss the architecture and implementation concerns
  • Timely: periodically reviews, updates, and adapts the architecture as necessary to align with new or changing business objectives and advances in industry, technology, and best practices
Good API Qualities - generally speaking, only violate with good reason
  • Easy to learn, use, and extend API without documentation
  • Hard to misuse the API, no ambiguity
  • Easy to read and maintain code that uses the API
  • API design is not a solitary activity, collaborate and carefully consider all opinions
  • Favor unchecked exceptions over checked exceptions
  • Never fail silently; don't swallow exceptions
  • Don't use exceptions for flow control
  • Include failure capture information in exceptions
  • Methods should have three or fewer parameter
  • Method parameters have consistent ordering
  • Fluent style for ease of reading and use
  • Return zero length arrays or empty collections instead of null
  • Parameters types should be as specific as possible, ideally not Strings
  • Service Provider Interface (SPI) - write two - three implementation minimum
  • Functionality should be small and easy to explain and name or it's a sign of over-complexity
  • Implementation should not impact API
  • Minimize accessibility of everything
  • Names matter, be consistent
  • Document everything
  • Consider performance implications of API
  • Favor immutability
  • Inheritance violates encapsulation: design and document or prohibit inheritance with final
  • Favor Composition over Inheritance
  • Subclass only where is-a relationship, otherwise utilize composition
  • Reduce the need for boilerplate
  • Don't violate principle of least astonishment - users of the API shouldn't be surprised
  • Fail-fast: as soon as possible, ideally compile time
  • Provide access to all data available in Strings, don't make clients parse Strings
  • Overload with care to avoid ambiguous behavior, ideally use different names
  • 12 factor app
Design Principles
Highly modular
  • loose coupling - knowledge of other components, general interface dependency is best
  • high cohesion - belong together, easy to understand and maintain
Principle of Least Knowledge (Law of Demeter)
  • Single Responsibility
  • Open for extension, Closed for modification
  • Liskov Substitution Principle - Design by Contract
  • Interface Segregation
  • Dependency Inversion
Tools
  • Structure101: modularity, dependency, visibility visualization and enforcement, $400-$1K
  • Enterprise Architect: forward/reverse engineering, comprehensive, *nix w/wine, <$1K
  • IBM Rational Rose: forward/reverse engineering, comprehensive, *nix compatible, >$3K
  • Visual Paradigm: Eclipse/intellij integration, full featured, *nix, $700-$1400
  • ObjectAid: Eclipse, class, sequence, forward/reverse engineering, *nix, $19
  • Gliffy: web based, no forward/reverse engineering, $8/mo
  • Cacoo: web based, no forward/reverse engineering, $5/mo
  • Lucidchart: web based, no forward/reverse engineering, $9/mo
  • Diagramly: web based, free
Use a Checklist
#78 It Takes Diligence
Effective architects often follow mundane daily and weekly checklists to remind
them of that which they already know academically, but fail to practice by habit. Without such
mundane checklists and reminders architects can quickly fall into software time, in which no
measurable progress is achieved because a lack of diligence allowed the architecture to meander
and violate known academic principles.

Comments

Post a Comment

Popular posts from this blog

Sites, Newsletters, and Blogs

BLOGS Java.net Weblogs Martin Fowler's blog Paul Graham Ruminations of a Programmer Form Follows Function Newsletters Core Java Tech Tips Enterprise Java Tech Tips JavaSpecialists.EU TheServerSide.com Sites Java.net Today Hot Java Sites CSS Zen Garden Evernote Hacker News Pragmatic Programmer
Read more

Oracle JDBC ReadTimeout QueryTimeout

If a query exceeds the oracle.jdbc.ReadTimeout without receiving any data, an exception is thrown and the connection is terminated by the Oracle driver on the client. Unfortunately the session will still be queued on the database and continue to wait for locks, hold any current locks, and complete any DML/PL*SQL procedures that are pending on the server-side of the orphaned connection. If an application, on a another connection, due to ReadTimeout exception, retries DML/PL*SQL  which requires locks, those queries will queue behind the initial DML/PL*SQL. This will increase the workload exacerbating the situation. On applications with retries, this can be observed by querying the v$session table  or gv$session on RAC and noting new sessions started periodically based on the ReadTimeout interval. The sessions may often have the same SQL_ID and/or SQL_HASH_VALUE. If stmt.setQueryTimeout(Seconds) is issued and the statement exceeds the timeout, it will atte...
Read more

Locks held on Oracle for hours after sessions abnormally terminated by node failure

If a session holds db locks and is abnormally terminated (no fin/ack), the locks will persist until the db session is closed, typically around 2 hours and 12 minutes with default network tcp_keepalive settings. Abnormally terminated does not include CTRL C or kill -9. The ojdbc6 driver apparently has a shutdown hook thread that closes the connections in graceful shutdowns. The OS apparently closes the connections when processes are killed. Abnormally terminated might include power failure, firewall failures, Out Of Memory, OS/kernel crash, network connection failure, JBoss or other server node failure, etc. This was easily reproduced by creating a  process that connected to the db and updated a record but did not commit. While the first process was waiting, a second process with a contending update was started which blocked on the first update. The first clients network cable was then disconnected. The second clients transaction waited for approximately 2 hours until the databa...
Read more