Software Design is a secondary research project aiming at creating a library of software design practices: short pieces of software design advice like "embed units in names of variables of time", "make functions private if possible", etc. The practices can be used during code reviews as actionable items and can help improving someone's software design skills (apart from improving the reviewed code itself).
The practices will be drawn from a number of resources, including books: "Refactoring", "Effective Java", "Effective C++", "A Philosophy of Software Design", "The Pragmatic Programmer", "Clean Code", etc.), as well as similar, language-specific lists of practices that have recently emerged: http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines, https://golang.org/doc/effective_go.html, https://github.com/golang/go/wiki/CodeReviewComments, Wikipedia, Wikibooks, etc.
Apart from being used during code reviews directly, the secondary goals of the project are:
- Connect ideas from different resources.
- Promote static/automated analysis by referencing tools that enforce the practice in different programming languages.
The first example of a practice: Don't add a parameter that won't be used.
About the project
- Competing with the articles in Wikipedia's Software Design category. Whenever reasonable, an article in Wikipedia should be referenced from this project (and, perhaps, improved) instead of creating a duplicating page in the space of the Software Design project.
- Competing with Martin Fowler's Bliki and catalog of refactorings. These should be treated as resources for the project and referenced when appropriate.
- Covering software development topics extensively. The main scope of the Software Design project are the "static" properties of software, not about the dynamics of engineering teams, projects, communication, methodologies, etc. However, software design cannot be considered in complete separation from the broader software engineering topics, so the pages in this project are expected to discuss some aspects of software development (testing, methodologies, long-term project dynamics), for example, making arguments for some practices.
The research method of the project is analyzing how every practice affects the qualities of the software: whether it makes the code better or worse in terms of a specific quality. All qualities are broadly split into three categories:
- Software qualities: (money) cost, speed, resource usage, reliability, (binary) size, etc.
- Interface qualities: hard/easy to misuse, reliability, interface size (the number of elements), naturality, etc.
- Code qualities: complexity, modularity, easiness of change, robustness (against programming error), (screen) size, etc.
Primary vs. high-level qualities
Many resources on software design operate with high-level qualities such as usability, steepness of learning curve, readability, understandability, maintainability, flexibility, easiness of change, and complexity (in a broader sense rather than in the narrower sense used in the project). These qualities are derived from a blend of lower-level primary qualities which are sometimes even at odds with each other. For example, readability is derived from obviousness, clarity, structuredness, and naturality.
Practices in the project should be analyzed in the context of primary, not high-level qualities. Consider these two statements:
var c = a / b
var yieldPerHectare: Double = totalYield / numHectares
The first is clearer, the second is more obvious. Which one is more readable is subjective because it depends on whether the reader prefers clarity or obviousness in code, as well as his familiarity with the codebase, the surrounding code, and other factors. Therefore, appealing to high-level qualities might be ambiguous and subjective which doesn't align with the goals of Software Design project.
Criterion for defining a quality: independence (at least, sometimes) from all other qualities
Neutral point of view
Software design is a subjective topic: different programmers value different primary software qualities differently. The Software Design project aims to maintain neutrality by objectively presenting how each practice and refactoring affects different primary software qualities, but not arguing that one quality is more important than another (after all, apart from being a subject for personal preferences, the relative importance of different primary qualities varies a lot from project to project, and even in different contexts and at different times within the same project).
Programming language of examples
Code examples in the project are mostly written in Kotlin but this is not a hard rule.
val keyword should be avoided (