Announcing Software Design learning project
About half a year ago, I’ve started Software Design learning project on Wikiversity (a sister project of Wikipedia you’ve probably never heard about). In it, I describe software design practices: bite-sized pieces of advice on software design, such as Make if condition positive, Create "deep" functions, or Extract loosely coupled parts of a class into smaller classes.
Different practices apply to different software entities: some concern individual expressions and variables, others — functions, yet other practices apply to classes, modules, and packages. From another perspective, there are practices in different areas of software design: naming, error handling, complexity management, abstraction, etc.
Goals and motivation
The two main goals of the project are the following:
Collect questions for code review checklists
Each practice is a source of one or a few precious checklist questions. For example, the practice Make if condition positive includes the following question: “Would arranging if-else branches so that the condition is positive (like if (cond) instead of if (!cond) make the code simpler?”
Accumulated from all pages, these questions could be used selectively in checklists during code review.
One thing that 2019 has taught me is that checklists are huge. After creating the Java concurrency checklist, my ambition is a more general software design checklist. Admittedly, checklists of many dozens of questions (like the Java concurrency checklist) or even several hundred of questions (as the software design checklist is projected to be), are not practically digestible in full during a single code review, but I believe that filtering and sampling could be applied while a significant part of the value of a checklist is retained.
Connect ideas from books and online resources
A number of books are written on the topic of software design: “The Pragmatic Programmer”, “Refactoring”, “Clean Code”, “A Philosophy of Software Design”, “The Art of Readable Code”, etc., and many other popular books such as “Programming Pearls”, “Effective Java”, “Effective C++” include significant number of discrete software design advice, but all these books seldom reference each other. A goal of the Software Design learning project is to connect the ideas about software design across programming languages by referring to the books from the corresponding articles on practices.
There are also many online resources, including C++ Core Guidelines, .NET Framework Design Guidelines (as well as other “best practices” in .NET documentation), and Go Code Review Comments ideas from which would be nice to connect.
Status and plans
I estimate there are possibly about several hundred software design practices not specific to individual programming languages. At the moment of this announcement, only a few dozen practices are established, and only about 10 to 20 are relatively well-developed.
I write practices in my spare time. It’s likely that my pace will never be higher than it was in 2019. Given that, it may take more than 10 years for me alone to achieve good completion of the project.
I realize that it’s certain that over such a long period of time my interests and priorities will change, and the chances that I will actually keep working on the project for 10 years ahead are quite low. I haven’t given up already because writing and analyzing software design practices is intellectually joyful for me, and I think it clarifies my thinking about code which is helpful in my day job.
That being said, I wish the project was moving forward faster. So, if you think that writing about software design may be interesting, I invite you to join the project. There is no special procedure: Wikiversity is open for edit by anyone. For private communication, you could reach me at leventov.ru@gmail.com.
Similar projects
The idea of C++ Core Guidelines is very similar to the idea of the Software Design learning project, and the former was actually an inspiration for the latter. The only difference is that C++ Core Guidelines restricts itself to a single programming language.
Another similar project with the focus on Java and Web development is Java Practices, albeit it is not open for contribution.
Carnegie Mellon University — Software Engineering Institute hosts a group of “Coding Standards”: for Secure Coding, C, C++, Java, Android, and Perl.
.NET Framework Design Guidelines and best practices pages in .NET documentation are available for discussion and contribution via dotnet/docs repository on Github.
If you know about other similar projects, please let me know in the comments.
Why not a book?
I think that a wiki is a better medium than a book for a learning resource about software design. A wiki is not limited in size, so there is no material inclusion/exclusion dilemma. A wiki is not ordered and interlinked: a reader could start anywhere and proceed to any page. A wiki is available online for free and is open for continuous improvement and editing by any person.
