41–50 of 53 posts
There are dozens at the Architecture of Open Source Applications ebook/site: http://aosabook.org/en/index.html As someone who only really gets exposure to web tech, it was fascinating how other types of software is architected, too.
Perhaps Effective C++ comes in second, but that's just b/c C++ is a nightmare.
There are dozens at the Architecture of Open Source Applications ebook/site: http://aosabook.org/en/index.html As someone who only really gets exposure to web tech, it was fascinating how other types of software is architected, too.
The best book/pair of books about software that I have ever read. Perhaps Effective C++ comes in second, but that's just b/c C++ is a nightmare.
A little known, but powerful notation for description and documentation of architecture of Information Processing Systems is FMC http://www.fmc-modeling.org/ This site features a link to the Apache Modeling Project where a now outdated version of httpd was documented using this methodology.
Our design decision documents have essentially four sections: Problem description, solution options, comparison of the options, and decision. I find it helpful to clearly distinguish what is part of the problem and what part of the solution. The size of the sections varies a lot. Meta information could be: Status, stakeholders, decision-makers, and rollout description. It also often has links to meeting protocols and…
Yes please. So much this. With evidence, please, so that the decisions can be revisited in the future and changed when they no longer apply. Every day I open another source file on a system that was built over a decade by a rotating cast of mostly first job software engineers without adequate mentorship and (I wish I was making this up) having their C++ code reviewed by a C programmer who gave them comments such as "just turn all these functions into one-line macros", and someone who appeared to be mainlining late-nineties OOP hype like it was going out of fashion and needed to get it all on the page before someone beat him to death with an old Vic 20.
Every day we stare at it and ask ourselves why. Why was it done like this? Was there a good reason back then? Does that reason still exist? If I rewrite it to remove all this horror, will something else break? Even, oh God, even "What is this actually meant to do?" I can see what it does do. What it does do makes no sense. Did it ever make sense?
Even the occasional comment like "cheeky hack for performance" is often more hindrance than help when a quick test shows it actually makes performance worse. Did it ever improve things? Did the hardware change underneath it such that it no longer helps? Did other code change such that it no longer applies?
Anyway, where this was going is that a decision recorded without evidence or even the factors considered might as well have been a coin toss to the software archaeologist having to maintain it in a decade's time. If the decisions and reasoning aren't recorded, you're forcing someone to attempt to reverse-engineer your state of mind, and that's an expensive and impossible job.
Earlier quoted context omitted.
The best book/pair of books about software that I have ever read. Perhaps Effective C++ comes in second, but that's just b/c C++ is a nightmare.
Effective C++ is mostly just a book about C++ pitfalls to avoid. It says nothing about high level concepts.
I’m a huge fan of code as design [1], so I tend to do my architecture thinking at a high level - the objects and interactions between systems - and then write clear and simple code which expresses my intention. To this end, if the code is clear then it doesn’t need to be documented heavily. I’m also a big fan of DDD [2] and use his “box and line” drawings all the time. There are loads of resources for DDD but I’ve li…
https://www.cs.colorado.edu/~kena/classes/5448/f12/presentat...
Don’t do it like me and overthink it. Just write down all your thoughts informally. Make diagrams by hand. Only once you have most content then think about formatting and structure. A lot of people produce nicely looking docs without much content. I much prefer a bunch of simple notes that describe the thought process
I agree. I used to work on a project where everyone involved in the initial design had left the company, and documentation was spotty. The major issues I had working with the code were all related to not understanding the underlying design choices, e.g. why a certain model was chosen over another or how a certain abstraction was intended to be extended with new functionality. Stuff that can be formalized in a systema…