Design Critque - Page 1
Forum section: electronics / general

author: westfw
author_rank: Super Contributor
timestamp: April 30, 2023, 10:34:39 pm
content: So...I think I basically know how to write "requirements documents", "functional specifications", and "design specifications." (All covered in those ISO9000 training classes, you know.)But I think I need some advice on how I should write a "Critique" of an existing design. Basically, somehow enumerating all the things thatshouldhave been caught during the reviews of the requirements, specs, and implementation, but ... that chance was years ago (if such reviews ever happened at all), and now I'm looking to lay the groundwork for a re-write...Essentially "this existing code/structure sucks because xxx", but in a nice and professional way, so that the stakeholders might listen instead of just getting defensive.I suppose that one strategy would be to write a "functional specification" for how you think it SHOULD work, and then highlighting the ways in which the current implementation fails to do those things?Thoughts?

author: dobsonr741
author_rank: Frequent Contributor
timestamp: April 30, 2023, 11:06:03 pm
content: Are you writing a justification for a redesign or code rewrite?If so it’s different from a code review. A rewrite decision is not based on the correctness or the proper implementation of the requirements, like a code review, rather based on the issues and gaps, perhaps excessive costs discovered after using/operating/running the code.

author: Tomorokoshi
author_rank: Super Contributor
timestamp: May 01, 2023, 12:49:45 am
content: If you generalize away somewhat from the "reviews" point of view, then you can compare the entirety of the old solution with (to the extent it can be defined) best practices for today. For instance:1. Is all source code and relevant tools properly commented and labeled in source control?2. Are all releases labeled in source control?3. Is the compiler up to date? The IDE? Any other tools?4. Is it dependent on brittle license servers?5. Is it dependent on 3rd party software libraries that may not be up to date?6. Is it up to date with modern security methods?7. Did the software design slowly build up deprecated methodologies and fixes upon fixes?8. Is the software design able to support the requested new features?9. If necessary, is the code base portable to some other platform?10. Is the code base dependent on a singular guru?11. Is the code base documented?12. Is the user base / audience of the product understood?13. Is the project manager a software engineer?14. What is the patience level / timeline of generating a report?I get the whole "stakeholders" thing. There are some interesting dynamics that happen when a complex design base becomes controlled by antsy project managers.

author: Infraviolet
author_rank: Super Contributor
timestamp: May 01, 2023, 11:33:25 pm
content: "this existing code/structure sucks because xxx"Point out all the various failure modes the current horrible code/structure has. Explain in detail how easily any of the faults could be triggered (race condition, computer starts a background task at just the wrong time, network connectivity fails right between doing A and starting B...) and how each could lead to a serious consequence. That ought to make it clear what is wrong. Tomorokoshi's list provides some ideas of things which could be other causes of problems, follow them through to their end result except where an obvious workaround to prevent such flaws is apparent (or example third party libraries perhaps might not matter if you can ensure only local copies of the version the codebase was built to use are present, that they don't get changed and that they ship with the code everywhere it goes, and that the whole thing is fully offline so any security matters wouldn't be relevant).On the other hand, if you can't point out how the current terrible setup can actually lead to failures because of seemingly innocous inputs, then it might seem awful and terrible but perhaps it is sufficiently functional to be just about acceptable (if the user is happy with the system as is and would never need to make changes to it or updates upon it which would end up with the one single expert who never documented his code having to go back through ancient and terribly confusingly arranged files...).

author: westfw
author_rank: Super Contributor
timestamp: May 04, 2023, 12:14:43 am
content: Quote(and etc)Most of those are "process" issues, and while I did mention ISO9000, in this case I'm only really interested in critiquing the technical design of some software where those issues aren't really relevant. "I want to re-write Arduino's digitalWrite() function because the code is checked in via git instead of svn" doesn't, and shouldn't, be a thing.(MAYBE, if all you're doing is re-organizing the source code, you can get away with this sort of thing, but not if you want to change the underlying algorithms and data structures.)

author: westfw
author_rank: Super Contributor
timestamp: May 04, 2023, 12:22:51 am
content: QuoteWell, yeah. Those sorts of situations are what I want to critique. "X is OK if all you do is the things that are currently possible, but it isn't extensible and doesn't allow for Y. And by the way it could be more efficient."The specific example is Arduino's SAMD g_APinDescription array, which is used for translating between the "board pin numbers" that Arduino uses, and assorted hardware-specific details (Port, bit, Timer and Timer Channel, ADC channel, etc.) Currently it doesn't allow for a pin to implement multiple functions (which almost all of the pins COULD do) without the higher level code having intimate knowledge of the hardware details.

author: dobsonr741
author_rank: Frequent Contributor
timestamp: May 04, 2023, 03:24:32 am
content: A good way of learning to write justifications is to tell what happens if we do nothing.