Since design ideas, and even the concept of Physical Design (exactly where you put your files), are such a broad topic, may I give a definite example and ask for feedback on the example?

Suppose you are tasked with making a C++ application that does a whole bunch of complex mathematics. And, beforehand, you are given the types, structure etc. of all the inputs you will be responsible for, and the same for all outputs. And, of course, instructions on what the brain/engine/black-box inside your application should do to transform those inputs to the outputs.

Now let's say you just finished a fully functional but quickly put together first draft where you put everything in a library called math-engine. To emphasize the issue I'll come to shortly, let's assume you added Doxygen documentation to all of the public interfaces within your library... and that 10% of the public interfaces from said Doxygen documentation cover all of the input and output cases you were given. 90% of the public interfaces in that Doxygen documentation are for "low level" worker classes that users of your library will never know about (but you happily documented as you knew you would be using those classes to make the library).

Forgetting that you jumped right in with an implementation without considering design, you write an installation script that will install the binary from your release build and the header files your users will need... even as you polish the public API documenting those to-be installed headers (i.e. polish the 10% of your Doxygen docs mentioned above).

If you were to pause there and ask yourself, is the physical design of putting everything in one library the most effective thing I could have done? What would your answer to yourself be? What design would have been better?

If the context is too "tidy" to fire up an impulse to put on your design hat, imagine the same situation as above... except this time you were not given any information on the inputs and outputs of your application. Instead, you were just told what type(s) of problems your brain/engine/black-box should solve and asked to come up with a useful "public API" for the world to use [that corresponds to the headers you would have installed on users' machines]. And, to motivate the need for design a bit more: Assume you were told that, in the future, your application would be asked to solve more types of problems, even as you might eventually be given definite requests surrounding new input/output arrangements to code-up and include in the user's "public API". How might you refactor something like this given that you just created a fully functioning first draft in a single math-engine library with those same Doxygen docs mentioned above to boot (with the same 10%/90% split).

  • 1
    $\begingroup$ What do you mean "the most effective thing"? As opposed to what, or how do you measure success here? In any case, designing a public interface (or software in general) is hard. The more you know about the problem you are solving, the better your chances of coming up with a good solution. Building software is a journey in learning, and you iteratively improve on your solution as you learn more. $\endgroup$
    – Juho
    Jun 26, 2023 at 18:15
  • $\begingroup$ @Juho Thanks for the response. I clarified the 'If the context is too "tidy"' since your response posted. Does that extra prompt spark any kind of design pattern ideas, physical design ideas or the like? By the way, I agree with everything you wrote. I'm just wondering if someone would respond with something like "Why didn't you use such and such pattern/principle [for the purposes of making the code more easily extensible or simpler to reason about or...]?" along with a reference or two on the pattern/principle. $\endgroup$
    – tarstevs
    Jun 26, 2023 at 18:31
  • $\begingroup$ For a long time, people believed that if they just tried hard enough, analyzed the problem for long enough and all that before they got to work, they would come up with the best design and solution. This was called waterfall - nowadays there is a good amount of evidence that we are better off assuming that we will get the design and whatever wrong, and work incrementally and iteratively. So if someone says that and you think she has a point, isn't that only good? You can then improve on your design, API or whatever it is. $\endgroup$
    – Juho
    Jun 26, 2023 at 19:03
  • $\begingroup$ If possible, drop Doxygen, the cause of all evils. Otherwise, only document the public API entries. Use one header file per class in a single folder or a single header for the whole library. $\endgroup$
    – user16034
    Jun 26, 2023 at 19:17
  • $\begingroup$ Please use this site only to ask about actual problems you are facing. (See our help center.) This all sounds too vague and hypothetical and open-ended to be a good fit here, to me. I can't tell what your actual problem is. I'm not sure whether "design patterns" are on-topic here; they tend to be a bit subjective, and you might have better luck asking on Software Engineering.SE rather than here. $\endgroup$
    – D.W.
    Jun 26, 2023 at 21:24


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Browse other questions tagged or ask your own question.